Verwenden Sie substitutions
in Ihrer Build-Konfigurationsdatei dazu, bestimmte Variablen zum Build-Zeitpunkt zu ersetzen.
Substitutionen sind für Variablen geeignet, deren Wert bis zur Erstellung des Builds nicht bekannt ist. Mit Substitutionen können Sie auch eine vorhandene Build-Anfrage mit anderen Variablenwerten wieder verwenden.
Mit Cloud Build können Sie die bereits integrierten Substitutionen verwenden oder eigene Substitutionen definieren. Verwenden Sie substitutions
in der steps
und images
Ihres Builds, um deren Werte bei der Build-Erstellung aufzulösen.
Auf dieser Seite wird erläutert, wie Sie Standardsubstitutionen verwenden oder Ihre eigenen substitutions
definieren.
Standardsubstitutionen
Cloud Build bietet die folgenden Standardsubstitutionen für alle Builds:
$PROJECT_ID
: ID Ihres Cloudprojekts$BUILD_ID
: ID Ihres Builds$PROJECT_NUMBER
: Ihre Projektnummer$LOCATION
: die mit Ihrem Build verknüpfte Region
Cloud Build bietet die folgenden Standardsubstitutionen für Builds, die von Triggern aufgerufen werden:
$TRIGGER_NAME
: der mit dem Trigger verknüpfte Name$COMMIT_SHA
: die mit Ihrem Build verknüpfte Commit-ID$REVISION_ID
: die mit Ihrem Build verknüpfte Commit-ID$SHORT_SHA
: die ersten sieben Zeichen vonCOMMIT_SHA
$REPO_NAME
: der Name Ihres Repositorys$REPO_FULL_NAME
: der vollständige Name Ihres Repositorys, einschließlich Nutzer oder Organisation$BRANCH_NAME
: der Name Ihres Branch$TAG_NAME
: der Name Ihres Tags$REF_NAME
: der Name Ihres Zweigs oder Tags$TRIGGER_BUILD_CONFIG_PATH
: Der Pfad zu Ihrer Build-Konfigurationsdatei, die während der Build-Ausführung verwendet wird. Andernfalls ein leerer String, wenn Ihr Build inline im Trigger konfiguriert ist oder einDockerfile
- oderBuildpack
-Element verwendet.$SERVICE_ACCOUNT_EMAIL
ist die E-Mail-Adresse des Dienstkontos, das Sie für den Build verwenden. Dies ist entweder ein Standarddienstkonto oder ein benutzerdefiniertes Dienstkonto.$SERVICE_ACCOUNT
: der Ressourcenname des Dienstkontos im Formatprojects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL
Cloud Build bietet die folgenden GitHub-spezifischen Standardsubstitutionen, die für Pull-Anfrage-Trigger verfügbar sind:
$_HEAD_BRANCH
: oberster Zweig der Pull-Anfrage$_BASE_BRANCH
: Basiszweig der Pull-Anfrage$_HEAD_REPO_URL
: URL des Head-Repositorys der Pull-Anfrage$_PR_NUMBER
: Nummer der Pull-Anfrage
Wenn keine Standardsubstitution verfügbar ist, z. B. in Builds ohne Quelle oder in Builds, die eine Speicherquelle verwenden, werden fehlende Variablen durch einen leeren String ersetzt.
Wenn Sie einen Build mit gcloud builds submit
starten, können Sie mit dem Argument --substitutions
Variablen angeben, die normalerweise aus ausgelösten Builds übergeben werden. Insbesondere haben Sie die Möglichkeit, manuell Werte für folgende Variablen bereitzustellen:
$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
Der folgende Befehl verwendet beispielsweise die Substitution TAG_NAME
:
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=TAG_NAME="test"
Im folgenden Beispiel werden die Standardersetzungen $BUILD_ID
, $PROJECT_ID
, $PROJECT_NUMBER
und $REVISION_ID
verwendet.
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', 'gcr.io/$PROJECT_ID/my-image', '.']
# my-image is pushed to Container Registry
images:
- 'gcr.io/$PROJECT_ID/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"
]
}
Das folgende Beispiel zeigt, wie eine Build-Anfrage den Build-Schritt docker
verwendet, um ein Image zu erstellen, und das Image dann mit der Standardsubstitution $PROJECT_ID
per Push in Container Registry überträgt:
In diesem Beispiel:
- Die Build-Anfrage enthält einen Build-Schritt, der den Build-Schritt
docker
ingcr.io/cloud-builders
verwendet, um das Docker-Image zu erstellen.- Das Feld
args
im Build-Schritt definiert die Argumente, die an dendocker
-Befehl übergeben werden sollen. In diesem Fall wirdbuild -t gcr.io/my-project/cb-demo-img .
aufgerufen (nachdem$PROJECT_ID
durch Ihre Projekt-ID ersetzt wurde).
- Das Feld
Das Feld
images
enthält den Namen des Images. Wenn der Build erfolgreich ist, wird das resultierende Image per Push in Container Registry übertragen. Wenn das Image während des Build-Prozesses nicht erstellt wird, schlägt der Build fehl.
YAML
steps:
- name: gcr.io/cloud-builders/docker
args: ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
images:
- gcr.io/$PROJECT_ID/cb-demo-img
JSON
{
"steps": [{
"name": "gcr.io/cloud-builders/docker",
"args": ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
}],
"images": [
"gcr.io/$PROJECT_ID/cb-demo-img"
]
}
Benutzerdefinierte Substitutionen verwenden
Sie können außerdem Ihre eigenen Substitutionen definieren. Benutzerdefinierte Substitutionen müssen folgende Kriterien erfüllen:
- Substitutionen müssen mit einem Unterstrich (
_
) beginnen und dürfen entsprechend dem regulären Ausdruck_[A-Z0-9_]+
nur Großbuchstaben und Ziffern enthalten. Dadurch werden Konflikte mit integrierten Substitutionen verhindert. Zum Verwenden eines Ausdrucks, der mit$
beginnt, müssen Sie$$
verwenden. Das heißt:$FOO
ist ungültig, da es sich nicht um eine integrierte Substitution handelt.$$FOO
ergibt den Literalstring$FOO
.
- Die Anzahl der Parameter ist auf 200 Parameter beschränkt. Die Länge des Parameterschlüssels ist auf 100 Byte und die Länge des Parameterwerts auf 4.000 Byte begrenzt.
Sie können Variablen auf zwei Arten angeben: $_FOO
oder ${_FOO}
:
- Sowohl
$_FOO
als auch${_FOO}
ergeben den Wert_FOO
.${}
lässt jedoch die Ersetzung ohne umgebende Leerzeichen zu, damit Substitutionen wie${_FOO}BAR
möglich sind. - Mit
$$
können Sie eine Literal$
in die Vorlage einfügen. Das heißt:$_FOO
wird mit dem Wert von_FOO
ausgewertet.$$_FOO
ergibt den Literalstring$_FOO
.$$$_FOO
ergibt den Literalstring$
, gefolgt vom Wert von_FOO
.
Wenn Sie Substitutionen verwenden möchten, fügen Sie dem gcloud
-Befehl das Argument --substitutions
hinzu oder geben die Substitutionen in der Konfigurationsdatei an.
Das folgende Beispiel zeigt eine Build-Konfiguration mit den beiden benutzerdefinierten Substitutionen _NODE_VERSION_1
und _NODE_VERSION_2
.
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build',
'--build-arg',
'node_version=${_NODE_VERSION_1}',
'-t',
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
'.']
- name: 'gcr.io/cloud-builders/docker'
args: ['build',
'--build-arg',
'node_version=${_NODE_VERSION_2}',
'-t',
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}',
'.']
substitutions:
_NODE_VERSION_1: v6.9.1 # default value
_NODE_VERSION_2: v6.9.2 # default value
images: [
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}'
]
JSON
{
"steps": [{
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"--build-arg",
"node_version=${_NODE_VERSION_1}",
"-t",
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
"."
]
}, {
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"--build-arg",
"node_version=${_NODE_VERSION_2}",
"-t",
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}",
"."
]
}],
"substitutions": {
"_NODE_VERSION_1": "v6.9.1"
"_NODE_VERSION_1": "v6.9.2"
},
"images": [
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}"
]
}
Verwenden Sie zum Überschreiben des in der Build-Konfigurationsdatei angegebenen Substitutionswerts im Befehl gcloud builds submit
das Flag --substitutions
. Beachten Sie, dass Substitutionen eine Zuordnung von Variablen zu Werten sind, nicht zu Arrays oder Sequenzen. Sie können die Werte der standardmäßigen Substitutionsvariablen außer $PROJECT_ID
und $BUILD_ID
überschreiben. Der folgende Befehl überschreibt den Standardwert für _NODE_VERSION_1
, der in der Build-Konfigurationsdatei oben angegeben wurde:
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .
Standardmäßig gibt der Build einen Fehler zurück, wenn eine Substitutionsvariable oder eine Substitution fehlt. Sie können jedoch diese Überprüfung mit der Option ALLOW_LOOSE
überspringen.
Das folgende Snippet gibt "Hello World" aus und definiert eine nicht verwendete Substitution.
Da die Substitutionsoption ALLOW_LOOSE
festgelegt ist, wird der Build trotz der fehlenden Substitution ausgeführt.
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"
}
}
Wenn Ihr Build von einem Trigger aufgerufen wird, ist die Option ALLOW_LOOSE
standardmäßig festgelegt. In diesem Fall gibt der Build keinen Fehler zurück, wenn eine Substitutionsvariable oder eine Substitution fehlt. Sie können die Option ALLOW_LOOSE
für Builds, die durch Trigger aufgerufen werden, nicht überschreiben.
Wenn die Option ALLOW_LOOSE
nicht angegeben ist, führen nicht übereinstimmende Schlüssel in der Substitutionszuordnung oder Build-Anfrage zu einem Fehler. Wenn beispielsweise in Ihrer Build-Anfrage $_FOO
enthalten ist und _FOO
in der Substitutionszuordnung nicht definiert ist, wird nach dem Ausführen des Builds oder beim Aufrufen eines Triggers ein Fehler ausgegeben, falls der Trigger Substitutionsvariablen enthält.
Die folgenden Ersatzvariablen enthalten immer einen leeren Standardstringwert, auch wenn Sie die Option ALLOW_LOOSE
nicht festlegen:
$REPO_NAME
$REPO_FULL_NAME
$BRANCH_NAME
$TAG_NAME
$COMMIT_SHA
$SHORT_SHA
Beim Definieren einer Substitutionsvariable sind Sie nicht auf statische Strings beschränkt. Sie haben auch Zugriff auf die Ereignisnutzlast, die den Trigger ausgelöst hat. Diese sind als Nutzlastbindungen verfügbar. Sie können auch Bash-Parametererweiterungen auf Substitutionsvariablen anwenden und den resultierenden String als neue Substitutionsvariable speichern. Weitere Informationen finden Sie unter Nutzlastbindungen und Bash-Parametererweiterungen in Substitutionen verwenden.
Dynamische Substitutionen
Sie können in einer benutzerdefinierten Substitution auf den Wert einer anderen Variablen verweisen. Setzen Sie dazu die Option dynamicSubstitutions
in der Build-Konfigurationsdatei auf true
. Wenn Ihr Build von einem Trigger aufgerufen wird, ist das Feld dynamicSubstitutions
immer auf true
gesetzt und muss nicht in der Build-Konfigurationsdatei angegeben werden. Wenn Ihr Build manuell aufgerufen wird, müssen Sie das Feld dynamicSubstitutions
auf true
setzen, damit die Bash-Parametererweiterungen beim Ausführen des Builds interpretiert werden.
Die folgende Build-Konfigurationsdatei zeigt die Substitutionsvariable ${_IMAGE_NAME}
, die auf die Variable ${PROJECT_ID}
verweist. Das Feld dynamicSubstitutions
ist auf true
gesetzt, sodass der Verweis angewendet wird, wenn ein Build manuell aufgerufen wird:
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
_IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image'
options:
dynamicSubstitutions: true
JSON
{
"steps": [
{
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"-t",
"${_IMAGE_NAME}",
"."
]
}
],
"substitutions": {
"_IMAGE_NAME": "gcr.io/${PROJECT_ID}/test-image"
},
"options": {
"dynamic_substitutions": true
}
}
Weitere Informationen finden Sie unter Bash-Parametererweiterungen anwenden.
Substitutionen zu Umgebungsvariablen zuordnen
Skripts unterstützen Substitutionen nicht direkt, aber Umgebungsvariablen. Sie können Substitutionen Umgebungsvariablen zuordnen, entweder automatisch alle auf einmal oder manuell, indem Sie jede Umgebungsvariablen selbst definieren.
Automatische Ersetzung von Karten
Auf Build-Ebene: Wenn alle Substitutionen automatisch Umgebungsvariablen zugeordnet werden sollen, die im gesamten Build verfügbar sind, legen Sie auf Build-Ebene für
automapSubstitutions
die Optiontrue
fest. Die folgende Build-Konfigurationsdatei zeigt beispielsweise die benutzerdefinierte Substitution$_USER
und die Standardersetzung$PROJECT_ID
, die Umgebungsvariablen zugeordnet sind: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" } }
Auf Schrittebene: Wenn Sie alle Substitutionen automatisch zuordnen und als Umgebungsvariablen in einem Schritt verfügbar machen möchten, setzen Sie das Feld
automapSubstitutions
in diesem Schritt auftrue
. Im folgenden Beispiel werden die Substitutionen nur im zweiten Schritt korrekt angezeigt, da die automatische Substitutionszuordnung nur hier aktiviert ist: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" }
Außerdem können Sie die Substitutionen als Umgebungsvariablen im gesamten Build verfügbar machen und dann in einem Schritt ignorieren. Setzen Sie
automapSubstitutions
auf Build-Ebene auftrue
und setzen Sie dann dasselbe Feld in dem Schritt, in dem Sie die Substitutionen ignorieren möchten, auffalse
. Im folgenden Beispiel wird die Projekt-ID im zweiten Schritt nicht ausgegeben, obwohl die Zuordnung von Substitutionen auf Build-Ebene aktiviert ist, daautomapSubstitutions
in diesem Schritt auffalse
gesetzt ist: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" }
Manuelle Kartenersetzungen
Sie können die Substitutionen Umgebungsvariablen manuell zuordnen. Jede Umgebungsvariable wird auf Schrittebene mit dem Feld env
definiert und der Umfang der Variablen wird auf den Schritt beschränkt, in dem sie definiert werden. Dieses Feld enthält eine Liste mit Schlüsseln und Werten.
Das folgende Beispiel zeigt, wie die Substitution $PROJECT_ID
der Umgebungsvariablen BAR
zugeordnet wird:
YAML
steps:
- name: 'ubuntu'
env:
- 'BAR=$PROJECT_ID'
script: 'echo $BAR'
JSON
{
"steps": [
{
"name": "ubuntu",
"env": [
"BAR=$PROJECT_ID"
],
"script": "echo $BAR"
}
]
}
Nächste Schritte
- Nutzlastbindungen und Bash-Parametererweiterungen in Substitutionen verwenden.
- Einfache Build-Konfigurationsdatei erstellen
- Weitere Informationen finden Sie unter Build-Trigger erstellen und verwalten.
- Builds manuell in Cloud Build starten