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

Cette page explique comment utiliser des liaisons de charge utile et appliquer des extensions de paramètre bash aux variables de substitution associées au 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 des 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ètres bash lorsque vous définissez ou mettez à jour un déclencheur de compilation dans la console Google Cloud et dans un fichier de configuration Cloud Build. De plus, vous pouvez appliquer des extensions de paramètres bash lorsque vous exécutez des compilations 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 :

Ouvrez la page Déclencheurs.
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.
Sous Variables de substitution, cliquez sur Ajouter une variable.
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.

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 relatives à la charge utile de l'événement dans les 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 dans la valeur de variable est utilisé comme point d'entrée pour accéder aux informations de la charge utile JSON de votre build:

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 provenant 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)`	Récupère 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 la charge utile de l'événement dans les variables de substitution à l'aide de liaisons de charge utile. Pour accéder à la charge utile JSON à partir d'un événement push, utilisez le préfixe csr ou body. Dans l'exemple suivant, le préfixe csr dans la valeur de variable est utilisé comme point d'entrée pour accéder aux informations de la charge utile JSON de votre build.

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.

Extension des paramètres bash

Vous pouvez appliquer des extensions de paramètres 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 :

Extensions Bash	Description
`${var}`	Étend 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 pour établir des correspondances avec les extensions de paramètres bash suivantes :

Extensions Bash	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 :

Ouvrez la page Déclencheurs.
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.
Sous Variables de substitution, cliquez sur Ajouter une variable.
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.

Ajoutez une valeur pour votre variable, 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 montre des exemples d'extensions de paramètres bash que vous pouvez appliquer à $BRANCH_NAME :

Nom de la variable	Extension de bash	Valeur de la variable	Description
`_BRANCH_LOWERCASE`	`${$BRANCH_NAME,,}`	`feature_secret_project_#v2`	tous les caractères de la chaîne sont mis en minuscules.
`_BRANCH_NO_SUFFIX`	`${_BRANCH_LOWERCASE%_\#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:
     dynamicSubstitutions: 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 dynamicSubstitutions, défini sur true dans l'exemple ci-dessus, permet d'interpréter les extensions de paramètres bash. Si votre compilation est appelée par un déclencheur, le champ dynamicSubstitutions 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 dynamicSubstitutions 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 à des variables associées à des liaisons de charge utile en créant une variable pour référencer la variable contenant votre liaison ou en créant une chaîne de 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.

Étapes suivantes

Découvrez comment remplacer des valeurs de variable.
Découvrez comment créer un fichier de configuration de compilation de base.
Découvrez comment créer et gérer des déclencheurs de compilation.
Découvrez comment exécuter des compilations manuellement.