Utiliser des liaisons de charge utile et des extensions de paramètres bash dans les substitutions

Cette page explique comment utiliser les liaisons de charge utile et appliquer des extensions de paramètres bash aux variables de substitution associées à votre déclencheur de compilation. Si vous ne savez pas comment utiliser des variables de substitution dans votre configuration de compilation, consultez la section Remplacer des valeurs de variables.

Cloud Build vous permet de stocker des parties de la charge utile de l'événement de déclencheur en tant que variable de substitution. Une charge utile de l'événement est le corps de l'événement qui appelle un déclencheur. Les variables associées à une charge utile sont appelées liaisons et sont disponibles pour les compilations appelées par des événements push et pull. Les liaisons vous permettent d'accéder à des données supplémentaires liées à votre compilation, telles que la langue associée à votre code source et l'auteur d'une demande d'extraction.

Cloud Build permet également aux utilisateurs d'appliquer des extensions de paramètres bash aux valeurs de variables de substitution. Les extensions de paramètres Bash vous permettent de manipuler des chaînes associées à des variables existantes. Vous pouvez manipuler des chaînes en mettant des majuscules ou en remplaçant une sous-chaîne.

Vous pouvez utiliser des liaisons de charge utile et appliquer des extensions de paramètre bash lors de la définition ou de la mise à jour d'un déclencheur de compilation dans Google Cloud Console et dans un fichier de configuration Cloud Build. De plus, vous pouvez appliquer des extensions de paramètres bash lors de l'exécution de builds manuelles.

Liaisons de charge utile

Vous pouvez stocker des parties de la charge utile d'un événement de déclencheur en tant que valeur de variable de substitution. Les liaisons de charge utile sont disponibles en tant que valeurs variables pour les compilations appelées par des événements push et pull. Elles peuvent être utilisées pour accéder à la charge utile JSON lorsque votre code source se trouve dans les dépôts GitHub ou Cloud Source Repositories. Pour en savoir plus sur les charges utiles d'événements GitHub, consultez la page Charges utiles d'événements webhook. Pour en savoir plus sur les charges utiles d'événements pour Cloud Source Repositories, consultez la page Notifications pour Cloud Source Repositories.

Vous pouvez accéder aux informations de charge utile d'événement à l'aide d'un préfixe désigné, qui représente la racine de la charge utile de l'événement. À partir du préfixe, vous pouvez utiliser la syntaxe JSONPath pour accéder à la charge utile et extraire des données. Les préfixes de charge utile suivants sont disponibles en fonction de votre type d'événement :

Préfixe Source Description
push GitHub Vous permet d'accéder aux champs de la charge utile JSON pour les événements push
pull_request GitHub Vous permet d'accéder aux champs de votre charge utile JSON pour les événements de demande d'extraction.
issue_comment GitHub Vous permet d'accéder aux champs de votre charge utile JSON pour les événements de commentaires associés à une demande d'extraction
csr Cloud Source Repositories Vous permet d'accéder aux champs de la charge utile JSON pour les événements push

Pour tous les événements associés à l'application GitHub, les valeurs de variables intégrées is_collaborator et perm_level sont également disponibles. L'état de l'utilisateur est vérifié pour les événements push et pull par les valeurs de variable push.pusher.name, pull_request.pull_request.user.login et issue_comment.comment.user.login. Le tableau suivant montre comment les inclure en tant que valeurs de variables pour votre déclencheur lorsque votre code source est dans GitHub :

Nom de la variable Valeur de la variable Description de la variable
_PERM_LEVEL $(perm_level) Obtient le niveau d'autorisation de l'utilisateur
_IS_COLLABORATOR $(is_collaborator) Renvoie true si l'utilisateur est un collaborateur

Vous pouvez utiliser les valeurs de variable is_collaborator et perm_level pour les événements push, les événements de demande d'extraction et les événements de demande d'extraction déclenchés par un commentaire. Vous n'avez pas besoin de faire précéder ces valeurs de variable d'un préfixe.

Créer des substitutions à l'aide de liaisons de charge utile

Pour créer une variable de substitution qui utilise une liaison de charge utile :

  1. Ouvrez la page Déclencheurs.

  2. Si vous n'avez pas créé de déclencheur de compilation, cliquez sur Créer un déclencheur. Sinon, sélectionnez un déclencheur existant.

  3. Sous Variables de substitution, cliquez sur Ajouter une variable.

  4. Ajoutez un nom à votre variable en suivant les conventions décrites ci-dessous :

    • Les substitutions doivent commencer par un trait de soulignement (_) et contenir seulement des lettres majuscules et des chiffres (en respectant l'expression régulière [A-Z0-9_]+). Cela évite les conflits avec les substitutions intégrées.

    • Le nombre de paramètres est limité à 100. La longueur d'une clé de paramètre est limitée à 100 octets et la longueur d'une valeur de paramètre est limitée à 4 000 octets.

    Pour en savoir plus sur comment définir et utiliser des substitutions définies par l'utilisateur, consultez la page Utiliser des substitutions définies par l'utilisateur.

  5. Ajoutez une valeur pour votre variable, à l'aide d'un préfixe compatible.

    Si votre code source se trouve dans GitHub, vous pouvez faire référence aux informations de votre charge utile d'événement dans des variables de substitution à l'aide de liaisons de charge utile. Pour accéder à la charge utile JSON d'un événement push, utilisez le préfixe push ou body. Dans l'exemple suivant, le préfixe push de la valeur de la variable est utilisé comme point d'entrée pour accéder aux informations provenant de la charge utile JSON de votre compilation :

    Nom de la variable Valeur de la variable Description de la variable
    _PUSH_NAME $(push.repository.name) Obtient le nom du dépôt associé à l'événement push
    _COMMITS $(push.commits) Obtient le tableau d'objets de commit décrivant chaque commit envoyé
    _OWNER $(push.repository.owner.name) Obtient le nom du propriétaire du dépôt
    _URL $(push.repository.html_url) Obtient l'URL de votre dépôt GitHub
    _LANGUAGE $(push.repository.language) Obtient la langue du code source inclus dans l'évènement push

    Pour obtenir la liste des champs auxquels vous pouvez accéder à l'aide du préfixe push, consultez la page PushEvent.

    Pour accéder à la charge utile JSON d'un événement de demande d'extraction, utilisez le préfixe pull_request ou body. Dans l'exemple suivant, le préfixe pull_request de la valeur de la variable est utilisé comme point d'entrée pour accéder aux informations provenant de la charge utile JSON de votre compilation :

    Nom de la variable Valeur de la variable Description de la variable
    _PULL_REQUEST_ID $(pull_request.pull_request.id) Obtient l'ID de la demande d'extraction
    _PULL_REQUEST_TITLE $(pull_request.pull_request.title) Obtient le titre de la demande d'extraction
    _PULL_REQUEST_BODY $(pull_request.pull_request.body) Obtient le corps de la demande d'extraction
    _USERNAME $(pull_request.pull_request.user.login) Obtient le nom d'utilisateur de qui a envoyé la demande d'extraction
    _MERGE_TIME $(pull_request.pull_request.merged_at) Obtient l'heure de fusion de la demande d'extraction

    Pour obtenir la liste des champs auxquels vous pouvez accéder à l'aide du préfixe pull_request, consultez la page PullRequestEvent.

    Pour accéder à la charge utile JSON d'un événement de commit, utilisez le préfixe commit. Dans l'exemple suivant, le préfixe commit de la valeur de la variable est utilisé comme point d'entrée pour accéder aux informations de la charge utile JSON de votre compilation:

    Nom de la variable Valeur de la variable Description de la variable
    _COMMIT_URL $(commit.url) Récupère la date associée au commit.
    _COMMIT_USER $(commit.author.login) Récupère le nom d'utilisateur de l'auteur du commit.
    _COMMIT_MESSAGE $(commit.commit.message) Récupère le message associé au commit.
    _COMMIT_DATE $(commit.commit.committer.date) Récupère la date associée au commit.
    _COMMIT_ADDITIONS $(commit.files['*'].additions) Obtient le nombre d'ajouts associés aux fichiers du commit.

    Pour obtenir la liste des champs auxquels vous pouvez accéder à l'aide du préfixe commit, consultez la section Get a commit (Récupérer un commit).

    Si vous activez le contrôle des commentaires pour un déclencheur appelé par une demande d'extraction, l'événement qui appelle le déclencheur est un IssueCommentEvent et le préfixe associé est issue_comment. Dans les exemples suivants, le préfixe issue_comment de la valeur de la variable est utilisé comme point d'entrée pour accéder aux informations provenant de la charge utile JSON de votre compilation :

    Nom de la variable Valeur de la variable Description de la variable
    _PULL_REQUEST_ID $(issue_comment.issue.id) Obtient l'ID de la demande d'extraction
    _PULL_REQUEST_TITLE $(issue_comment.issue.title) Obtient le titre de la demande d'extraction
    _STATE $(issue_comment.state) Obtient l'état de la demande d'extraction (ouverte, fermée, etc.)
    _LABELS $(issue_comment.issue.labels) Obtient la liste des libellés associés à la demande d'extraction
    _LABELS_URL $(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url) Obtient l'URL associée au libellé correspondant à la description

    Pour obtenir la liste des champs auxquels vous pouvez accéder à l'aide du préfixe issue_comment, consultez la page IssueCommentEvent.

    .

    Si votre code source se trouve dans Cloud Source Repositories, vous pouvez faire référence aux informations de votre charge utile d'événement dans des variables de substitution à l'aide de liaisons de charge utile. Pour accéder à la charge utile JSON d'un événement push, utilisez le préfixe csr ou body. Dans l'exemple suivant, le préfixe csr de la valeur de la variable est utilisé comme point d'entrée pour accéder aux informations provenant de la charge utile JSON de votre compilation.

    Nom de la variable Valeur de la variable Description de la variable
    _REPO_NAME $(csr.name) Récupère le nom de votre dépôt.
    _REPO_URL $(csr.url) Récupère l'URL de votre dépôt.
    _CREATED_REPO $(csr.createRepoEvent) Indique si un utilisateur a créé un dépôt.
    _REF_EVENT_NAME $(csr.refUpdateEvent.refUpdates['*'].refName) Nom de la référence (par exemple, "refs/heads/primary-branch")

    Pour afficher des champs supplémentaires auxquels vous pouvez accéder dans Cloud Source Repositories, consultez la page Données de notifications.

Expansion des paramètres Bash

Vous pouvez appliquer des extensions de paramètre bash aux variables par défaut et aux variables définies par l'utilisateur. Voici quelques exemples d'opérations compatibles : remplacement de la sous-chaîne, segmentation de chaîne et utilisation des majuscules. Par exemple, vous pouvez remplacer une sous-chaîne dans une variable par défaut et l'utiliser comme tag d'image.

Les extensions de paramètres bash que vous pouvez spécifier pour les variables de substitution sont les suivantes:

Expansions de ce type Description
${var} Développe la valeur de chaîne stockée dans var
${var^} Met en majuscule le premier caractère de la chaîne
${var^^} Met en majuscule tous les caractères de la chaîne
${var,} Met en minuscules le premier caractère de la chaîne
${var,,} Met en minuscules tous les caractères de la chaîne
${var:position} Supprime les premiers caractères position de la chaîne
${var:position:length} Segmente la chaîne commençant par la valeur numérique spécifiée dans position et inclut les valeurs numérique jusqu'à celle spécifiée dans length
${var/substring/replacement} Remplace l'instance la plus à gauche de la valeur spécifiée dans substring par la valeur spécifiée dans replacement
${var//substring/replacement} Remplace toutes les instances de la valeur spécifiée dans substring par la valeur spécifiée dans replacement
${var/#substring/replacement} Remplace la première instance de la valeur spécifiée dans substring par la valeur spécifiée dans replacement uniquement si substring est un préfixe de var
${var/%substring/replacement} Remplace la dernière instance de la valeur spécifiée dans substring par la valeur spécifiée dans replacement uniquement si substring est un suffixe de var
${#var} Récupère la longueur de la chaîne
${var:-default} Évalue var à default, sauf si var est déjà défini

Vous pouvez également spécifier des modèles à mettre en correspondance pour les extensions de paramètres bash suivantes:

Expansions de ce type Description
${var#pattern} Supprime les caractères du côté gauche d'une chaîne jusqu'à l'instance la plus à gauche de l'élément pattern spécifié
${var##pattern} Supprime les caractères du côté gauche d'une chaîne jusqu'à l'instance la plus à droite de l'élément pattern spécifié
${var%pattern} Supprime les caractères situés à droite d'une chaîne jusqu'à la première instance de l'élément pattern spécifié
${var%%pattern} Supprime les caractères situés à droite d'une chaîne jusqu'à l'instance la plus à gauche de l'élément pattern spécifié

Vous pouvez définir les modèles suivants :

Format Description
* Correspond à zéro ou plusieurs caractères alphanumériques
? Correspond à un caractère alphanumérique
[ccc] Correspond à un caractère au format ccc, y compris les plages a-z ou 0-9
[^c] Correspond à tout caractère alphanumérique qui n'est pas au format c, y compris une plage de caractères où lo <= c <= hi
c Correspond à un caractère alphanumérique c
\c Correspond à un caractère c, y compris des caractères non alphanumériques tels que *, ? ou \

Appliquer des extensions de paramètres bash

Pour appliquer des extensions de paramètre bash à une variable de substitution intégrée ou définie par l'utilisateur, procédez comme suit:

  1. Ouvrez la page Déclencheurs.

  2. Si vous n'avez pas créé de déclencheur de compilation, cliquez sur Créer un déclencheur. Sinon, sélectionnez un déclencheur existant.

  3. Sous Variables de substitution, cliquez sur Ajouter une variable.

  4. Ajoutez un nom à votre variable en suivant les conventions décrites ci-dessous :

    • Les substitutions doivent commencer par un trait de soulignement (_) et contenir seulement des lettres majuscules et des chiffres (en respectant l'expression régulière [A-Z0-9_]+). Cela évite les conflits avec les substitutions intégrées.

    • Le nombre de paramètres est limité à 100. La longueur d'une clé de paramètre est limitée à 100 octets et la longueur d'une valeur de paramètre est limitée à 4 000 octets.

    Pour en savoir plus sur comment définir et utiliser des substitutions définies par l'utilisateur, consultez la page Utiliser des substitutions définies par l'utilisateur.

  5. Ajoutez une valeur à votre variable, en appliquant une extension de paramètre bash compatible à une variable de substitution intégrée ou à une autre variable de substitution définie par l'utilisateur.

    Dans l'exemple suivant, la variable de substitution intégrée $BRANCH_NAME a une valeur par défaut de feature_secret_project_#v2. Le tableau suivant présente des exemples d'expansions de paramètres bash que vous pouvez appliquer à $BRANCH_NAME:

    Nom de la variable Expansion étendue Valeur de la variable Description
    _BRANCH_NO_SUFFIX ${$BRANCH_NAME%_\#v2} feature_secret_project Supprime tous les caractères situés à droite de la chaîne correspondant au modèle spécifié
    _BRANCH_NO_PREFIX ${_BRANCH_NO_SUFFIX#*_} secret_project Supprime tous les caractères jusqu'au premier trait de soulignement
    _BRANCH_FOR_IMAGE_NAME ${_BRANCH_NO_PREFIX//_/-} secret-project Remplace tous les traits de soulignement par un tiret
    _IMAGE_NAME my-app-${_BRANCH_FOR_IMAGE_NAME}-prod my-app-secret-project-prod Construit le nom de l'image à l'aide de la variable _BRANCH_FOR_IMAGE_NAME définie ci-dessus

    Supposons que _IMAGE_NAME soit défini dans votre déclencheur comme la valeur spécifiée dans le tableau ci-dessus, my-app-secret-project-prod. Cette valeur remplacera désormais toute définition de _IMAGE_NAME dans votre fichier de configuration de compilation. Dans l'exemple suivant, la valeur de la variable spécifiée pour _IMAGE_NAME (my-app-secret-project-prod) remplace la valeur par défaut de _IMAGE_NAME (test-image) lorsque le déclencheur de compilation est appelé.

    YAML

     steps:
     - name: 'gcr.io/cloud-builders/docker'
       args: ['build',
              '-t',
              'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
              '.']
     substitutions:
         _IMAGE_NAME: test-image #default value
     images: [
         'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
     ]
     options:
         dynamic_substitutions: true
    

    JSON

     {
       'steps': [
         {
           'name': 'gcr.io/cloud-builders/docker',
           'args': [
             'build',
             '-t',
             'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
             '.'
           ]
         }
       ],
       'substitutions': {
         '_IMAGE_NAME': 'test-image' #default value
       },
       'images': [
         'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
       ],
       "options": {
         "dynamic_substitutions": true
       }
     }
    

Le champ dynamic_substitutions, défini sur true dans l'exemple ci-dessus, permet d'interpréter les extensions des paramètres bash. Si votre compilation est appelée par un déclencheur, le champ dynamic_substitutions est toujours défini sur true et n'a pas besoin d'être spécifié dans le fichier de configuration de compilation. Si votre compilation est appelée manuellement, vous devez définir le champ dynamic_substitutions sur true pour que les extensions de paramètres bash soient interprétées lors de l'exécution de la compilation.

Utiliser des extensions de paramètres bash avec des liaisons de charge utile

Vous pouvez appliquer des extensions de paramètre bash aux variables associées aux liaisons de charge utile en créant une variable pour référencer la variable contenant votre liaison, ou mettre en relation des liaisons avec des extensions de paramètres bash. Le tableau suivant répertorie des exemples d'utilisation de l'extension des paramètres bash avec des liaisons de charge utile:

Nom de la variable Valeur de la variable Description de la variable
_URL $(push.repository.html_url) Obtient l'URL du dépôt
_URL_CAPITAL ${_URL^^} Utilise une extension de paramètre bash pour mettre en majuscule tous les caractères de l'URL
_APP_NAME my-app-${_URL_CAPITAL} Ajoute un préfixe à l'URL en majuscule du dépôt
APP_NAME_ID my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7} Crée un nom d'application incluant l'URL du dépôt et les sept premiers caractères de l'ID de charge utile.

Étape suivante