Utilisez substitutions dans le fichier de configuration de compilation pour remplacer des variables spécifiques au moment de la compilation.
Les substitutions sont utiles pour les variables dont la valeur n'est pas connue avant la compilation ou pour réutiliser une demande de compilation existante avec différentes valeurs de variable.
Cloud Build propose des substitutions intégrées, mais vous avez également la possibilité de définir vos propres substitutions. Utilisez substitutions dans steps et images de votre compilation pour résoudre leurs valeurs au moment de la compilation.
Cette page explique comment utiliser les substitutions par défaut ou définir vos propres substitutions.
Utiliser des substitutions par défaut
Cloud Build fournit les substitutions par défaut suivantes pour toutes les compilations :
$PROJECT_ID: ID de votre projet Cloud$BUILD_ID: ID de votre compilation$PROJECT_NUMBER: votre numéro de projet$LOCATION: région associée à votre compilation
Cloud Build fournit les substitutions par défaut suivantes pour les compilations appelées par des déclencheurs :
$TRIGGER_NAME: nom associé à votre déclencheur$COMMIT_SHA: ID de commit associé à votre compilation$REVISION_ID: ID de commit associé à votre compilation$SHORT_SHA: les sept premiers caractères deCOMMIT_SHA$REPO_NAME: le nom de votre dépôt$REPO_FULL_NAME: nom complet de votre dépôt, y compris l'utilisateur ou l'organisation$BRANCH_NAME: le nom de votre agence$TAG_NAME: le nom de votre tag$REF_NAME: nom de votre branche ou de votre tag$TRIGGER_BUILD_CONFIG_PATH: chemin d'accès au fichier de configuration de compilation utilisé lors de l'exécution de la compilation. Sinon, chaîne vide si votre compilation est configurée de manière intégrée sur le déclencheur ou utilise unDockerfileou unBuildpack.$SERVICE_ACCOUNT_EMAIL: adresse e-mail du compte de service que vous utilisez pour la compilation. Il s'agit d'un compte de service par défaut ou d'un compte de service spécifié par l'utilisateur.$SERVICE_ACCOUNT: nom de ressource du compte de service, au formatprojects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL
Cloud Build fournit les substitutions par défaut suivantes propres à GitHub disponibles pour les déclencheurs de demande d'extraction :
$_HEAD_BRANCH: branche principale de la demande d'extraction$_BASE_BRANCH: branche principale de la demande d'extraction$_HEAD_REPO_URL: URL du dépôt principal de la demande d'extraction;extraction$_PR_NUMBER: numéro de la demande d'extraction
Si une substitution par défaut n'est pas disponible (par exemple, avec des compilations sans source ou avec des compilations qui utilisent une source de stockage), les occurrences de la variable manquante sont remplacées par une chaîne vide.
Lorsque vous démarrez une compilation à l'aide de gcloud builds submit, vous pouvez spécifier des variables qui proviendraient normalement de compilations déclenchées avec l'argument --substitutions. Plus précisément, vous pouvez indiquer des valeurs manuellement pour :
$TRIGGER_NAME$COMMIT_SHA$REVISION_ID$SHORT_SHA$REPO_NAME$REPO_FULL_NAME$BRANCH_NAME$TAG_NAME$REF_NAME$TRIGGER_BUILD_CONFIG_PATH$SERVICE_ACCOUNT_EMAIL$SERVICE_ACCOUNT
Par exemple, la commande suivante utilise la substitution TAG_NAME :
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=TAG_NAME="test"
L'exemple suivant utilise les substitutions par défaut $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER et $REVISION_ID.
YAML
steps:
# Uses the ubuntu build step:
# to run a shell script; and
# set env variables for its execution
- name: 'ubuntu'
args: ['bash', './myscript.sh']
env:
- 'BUILD=$BUILD_ID'
- 'PROJECT_ID=$PROJECT_ID'
- 'PROJECT_NUMBER=$PROJECT_NUMBER'
- 'REV=$REVISION_ID'
# Uses the docker build step to build an image called my-image
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/my-image', '.']
# my-image is pushed to Artifact Registry
images:
- '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/my-image'
JSON
{
"steps": [{
"name": "ubuntu",
"args": [
"bash",
"./myscript.sh"
],
"env": [
"BUILD=$BUILD_ID",
"PROJECT_ID=$PROJECT_ID",
"PROJECT_NUMBER=$PROJECT_NUMBER",
"REV=$REVISION_ID"
]
}, {
"name": "gcr.io/cloud-builders/docker",
"args": ["build", "-t", "gcr.io/$PROJECT_ID/my-image", "."]
}],
"images": [
"gcr.io/$PROJECT_ID/my-image"
]
}
L'exemple suivant présente une demande de compilation utilisant l'étape de compilation docker pour compiler une image, puis envoie l'image à Artifact Registry à l'aide de la substitution $PROJECT_ID par défaut :
Dans cet exemple :
- La demande de compilation comporte une étape de compilation, qui utilise l'étape de compilation
dockerdansgcr.io/cloud-builderspour compiler l'image Docker.- Le champ
argsde l'étape définit les arguments à transmettre à la commandedocker. Dans ce cas,build -t gcr.io/my-project/cb-demo-img .est appelé (une fois$PROJECT_IDremplacé par l'ID du projet).
- Le champ
Le champ
imagescontient le nom de l'image. En cas de réussite de la compilation, l'image obtenue est envoyée à Artifact Registry. En cas d'échec de la création de l'image par la compilation, cette dernière échoue.
YAML
steps:
- name: gcr.io/cloud-builders/docker
args: ["build", "-t", "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img", "."]
images:
- '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img'
JSON
{
"steps": [{
"name": "gcr.io/cloud-builders/docker",
"args": ["build", "-t", "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img", "."]
}],
"images": [
"${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img"
]
}
Utiliser des substitutions définies par l'utilisateur
Vous pouvez également définir vos propres substitutions. Les substitutions définies par l'utilisateur doivent être conformes aux règles suivantes :
- 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. Pour utiliser une expression commençant par$, vous devez utiliser$$. For example:$FOOis invalid since it is not a built-in substitution.$$FOO, qui renvoie la chaîne littérale$FOO.
- Le nombre de paramètres est limité à 200. 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.
$_FOOet${_FOO}équivalent à_FOO. Cependant,${}permet à la substitution de fonctionner sans espaces, ce qui permet des substitutions comme${_FOO}BAR.$$lets you include a literal$in the template. For example:$_FOOevaluates to the value of_FOO.$$_FOOrenvoie la chaîne littérale$_FOO.$$$_FOOevaluates to the literal string$followed by the value of_FOO.
$REPO_NAME$REPO_FULL_NAME$BRANCH_NAME$TAG_NAME$COMMIT_SHA$SHORT_SHAAu niveau de la compilation : Pour mapper automatiquement toutes les substitutions aux variables d'environnement, qui seront disponibles tout au long de la compilation, définissez
automapSubstitutionssurtruecomme option au niveau de la compilation. Par exemple, le fichier de configuration de compilation suivant montre la substitution définie par l'utilisateur$_USERet la substitution par défaut$PROJECT_IDmappées aux variables d'environnement :YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" options: automapSubstitutions: true substitutions: _USER: "Google Cloud"JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'" } ], "options": { "automap_substitutions": true }, "substitutions": { "_USER": "Google Cloud" } }Au niveau de l'étape : Pour mapper automatiquement tous les remplacements et les rendre disponibles en tant que variables d'environnement en une seule étape, définissez le champ
automapSubstitutionssurtruedans cette étape. Dans l'exemple suivant, seule la deuxième étape affichera correctement les substitutions, car c'est la seule pour laquelle le mappage des substitutions automatiques est activé :YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" automapSubstitutions: true substitutions: _USER: "Google Cloud"JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'", "automap_substitutions": true } ], }, "substitutions": { "_USER": "Google Cloud" }Vous pouvez également rendre les substitutions disponibles en tant que variables d'environnement dans l'ensemble de la compilation, puis les ignorer en une seule étape. Définissez
automapSubstitutionssurtrueau niveau de la compilation, puis définissez le même champ surfalseà l'étape où vous souhaitez ignorer les substitutions. Dans l'exemple suivant, même si les substitutions de mise en correspondance sont activées au niveau de la compilation, l'ID du projet ne sera pas imprimé lors de la seconde étape, carautomapSubstitutionsest défini surfalselors de cette étape :YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" automapSubstitutions: false options: automapSubstitutions: true substitutions: _USER: "Google Cloud"JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'", "automap_substitutions": false } ], "options": { "automap_substitutions": true }, }, "substitutions": { "_USER": "Google Cloud" }- Découvrez comment Utiliser des liaisons de charge utile et des extensions de paramètres bash dans les substitutions.
- 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 dans Cloud Build.
Vous pouvez spécifier des variables de deux manières, $_FOO ou ${_FOO} :
To use the substitutions, use the --substitutions
argument in the gcloud command
or specify them in the config file.
The following example shows a build config with two user-defined substitutions
called _NODE_VERSION_1 and _NODE_VERSION_2:
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build',
'--build-arg',
'node_version=${_NODE_VERSION_1}',
'-t',
'${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}',
'.']
- name: 'gcr.io/cloud-builders/docker'
args: ['build',
'--build-arg',
'node_version=${_NODE_VERSION_2}',
'-t',
'${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}',
'.']
substitutions:
_NODE_VERSION_1: v6.9.1 # default value
_NODE_VERSION_2: v6.9.2 # default value
images: [
'${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}',
'${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}'
]
JSON
{
"steps": [{
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"--build-arg",
"node_version=${_NODE_VERSION_1}",
"-t",
"${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}",
"."
]
}, {
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"--build-arg",
"node_version=${_NODE_VERSION_2}",
"-t",
"${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}",
"."
]
}],
"substitutions": {
"_NODE_VERSION_1": "v6.9.1",
"_NODE_VERSION_2": "v6.9.2",
},
"images": [
"${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}",
"${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}"
]
}
To override the substitution value you specified in the build config file,
use the --substitutions flag in the gcloud builds submit command. Note
that substitutions are a mapping of variables to values rather than arrays or
sequences. You can override default substitution variable
values except for $PROJECT_ID and $BUILD_ID. The following command overrides
the default value for _NODE_VERSION_1 specified in the previous build config
file:
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .
By default, the build returns an error if there's a
missing substitution variable or a missing substitution. However, you can set
the ALLOW_LOOSE option to skip this check.
The following snippet prints "hello world" and defines an unused substitution.
Because the ALLOW_LOOSE substitution option is set, the build will be
successful despite the missing substitution.
YAML
steps:
- name: 'ubuntu'
args: ['echo', 'hello world']
substitutions:
_SUB_VALUE: unused
options:
substitutionOption: 'ALLOW_LOOSE'
JSON
{
"steps": [
{
"name": "ubuntu",
"args": [
"echo",
"hello world"
]
}
],
"substitutions": {
"_SUB_VALUE": "unused"
},
"options": {
"substitution_option": "ALLOW_LOOSE"
}
}
If your build is invoked by a trigger, the ALLOW_LOOSE option is set by
default. In this case, your build won't return an error if there is a
missing substitution variable or a missing substitution. You cannot override
the ALLOW_LOOSE option for builds invoked by triggers.
If the ALLOW_LOOSE option is not specified, unmatched keys in your substitutions
mapping or build request will result in error. For example, if your build request
includes $_FOO and the substitutions mapping doesn't define _FOO, you
will receive an error after running your build or invoking a trigger if your
trigger includes substitution variables.
The following substitution variables always contain a default empty-string
value even if you don't set the ALLOW_LOOSE option:
When defining a substitution variable, you aren't limited to static strings. You also have access to the event payload that invoked your trigger. These are available as payload bindings. You can also apply bash parameter expansions on substitution variables and store the resulting string as a new substitution variable. To learn more, see Using payload bindings and bash parameter expansions in substitutions.
Dynamic substitutions
You can reference the value of another variable within a user-defined
substitution by setting the dynamicSubstitutions option to true in
your build config file. If your build is invoked by a trigger, the
dynamicSubstitutions field is always set to true and does not need to
be specified in your build config file. If your build is invoked manually,
you must set the dynamicSubstitutions field to true for bash parameter
expansions to be interpreted when running your build.
The following build config file shows the substitution variable ${_IMAGE_NAME} referencing the variable, ${PROJECT_ID}. The
dynamicSubstitutions field is set to true so the reference
is applied when invoking a build manually:
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
_IMAGE_NAME: '${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPOSITORY}/test-image'
options:
dynamicSubstitutions: true
JSON
{
"steps": [
{
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"-t",
"${_IMAGE_NAME}",
"."
]
}
],
"substitutions": {
"_IMAGE_NAME": "${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPOSITORY}/test-image"
},
"options": {
"dynamic_substitutions": true
}
}
For more information, see Applying bash parameter expansions.
Secret substitutions
You can substitute secrets from Secret Manager
in Cloud Build. To do so, include your substitution variable in
the value of the versionName field in your build config file.
The following example shows how to define a substitution for a secret version.
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
entrypoint: 'bash'
args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
secretEnv: ['USERNAME', 'PASSWORD']
availableSecrets:
secretManager:
- versionName: projects/$PROJECT_ID/secrets/my-docker-password/versions/$_SECRET_VERSION
env: 'PASSWORD'
- versionName: projects/$PROJECT_ID/secrets/my-docker-username/versions/latest
env: 'USERNAME'
substitutions:
_SECRET_VERSION: '1' #Default value for the secret version
JSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "entrypoint": "bash", "args": [ "-c", "docker login --username=$$USERNAME --password=$$PASSWORD" ], "secretEnv": [ "USERNAME", "PASSWORD" ] } ], "availableSecrets": { "secretManager": [ { "versionName": "projects/$PROJECT_ID/secrets/my-docker-password/versions/$_SECRET_VERSION", "env": "PASSWORD" }, { "versionName": "projects/$PROJECT_ID/secrets/my-docker-username/versions/latest", "env": "USERNAME" } ] }, "substitutions": { "_SECRET_VERSION": "1" } }Pour en savoir plus sur les secrets dans Cloud Build, consultez la section Utiliser des secrets depuis Secret Manager dans la documentation Cloud Build.
Mappage des substitutions aux variables d'environnement
Les scripts ne sont pas directement compatibles avec les substitutions, mais ils le sont avec les variables d'environnement. Vous pouvez mapper des substitutions à des variables d'environnement, soit automatiquement en une seule fois, soit manuellement en définissant vous-même chaque variable d'environnement.
Mettre en correspondance automatiquement les substitutions
Mappez manuellement les substitutions
Vous pouvez mapper manuellement les substitutions aux variables d'environnement. Chaque variable d'environnement est définie au niveau de l'étape à l'aide du champ env, et la portée des variables est limitée à l'étape où elles sont définies. Ce champ accepte une liste de clés et de valeurs.
L'exemple suivant montre comment mapper la substitution $PROJECT_ID à la variable d'environnement BAR :
YAML
steps:
- name: 'ubuntu'
env:
- 'BAR=$PROJECT_ID'
script: 'echo $BAR'
JSON
{
"steps": [
{
"name": "ubuntu",
"env": [
"BAR=$PROJECT_ID"
],
"script": "echo $BAR"
}
]
}
Étapes suivantes
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2026/07/13 (UTC).