Variablenwerte ersetzen

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 von COMMIT_SHA
• $REPO_NAME: der Name Ihres Repositorys
• $REPO_FULL_NAME: der vollständige Name Ihres Repositorys, einschließlich des Nutzers oder der Organisation
• $BRANCH_NAME: der Name Ihres Branch
• $TAG_NAME: der Name Ihres Tags
• $REF_NAME: der Name Ihres Branch oder Tags
• $TRIGGER_BUILD_CONFIG_PATH: Der Pfad zu Ihrer Build-Konfigurationsdatei, der während der Build-Ausführung verwendet wird. Andernfalls ein leerer String, wenn der Build inline am Trigger konfiguriert ist oder einen Dockerfile oder Buildpack verwendet.
• $SERVICE_ACCOUNT_EMAIL: E-Mail-Adresse des Dienstkontos, das Sie für den Build verwenden. Dies ist entweder ein Standarddienstkonto oder ein vom Nutzer angegebenes Dienstkonto.
• $SERVICE_ACCOUNT: Der Ressourcenname des Dienstkontos im Format projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL.

Hinweis: Sowohl $COMMIT_SHA als auch $REVISION_ID stehen für die Commit-ID, die Ihrem Build zugeordnet ist. Unterstützung für beide Substitutionen ist verfügbar.

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 Standardsubstitutionen $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', '${_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"
  ]
}

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 Artifact Registry überträgt:

In diesem Fall gilt Folgendes:

• Die Build-Anfrage enthält genau einen Build-Schritt, der den docker-Build-Schritt in gcr.io/cloud-builders dazu verwendet, das Docker-Image zu erstellen.
  • Das Feld args im Build-Schritt definiert die Argumente, die an den docker-Befehl übergeben werden sollen. In diesem Fall wird build -t gcr.io/my-project/cb-demo-img . aufgerufen (nachdem $PROJECT_ID durch Ihre Projekt-ID ersetzt wurde).

• Das Feld images enthält den Namen des Images. Wenn der Build erfolgreich ist, wird das resultierende Image per Push in Artifact 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", "${_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"
  ]
}

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 $$. For example:
  • $FOO is invalid since it is not a built-in substitution.
  • $$FOO verwenden. $$. For example:
    • $FOO is invalid since it is not a built-in substitution.
    • $$FOO ergibt den Literalstring $FOO.
  • Es sind maximal 200 Parameter zulässig. 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.
  • $$ lets you include a literal $ in the template. For example:
    • $_FOO evaluates to the value of _FOO.
    • $$_FOO ergibt den Literalstring $_FOO.
    • $$$_FOO evaluates to the literal string $ followed by the value of _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:

  • $REPO_NAME
  • $REPO_FULL_NAME
  • $BRANCH_NAME
  • $TAG_NAME
  • $COMMIT_SHA
  • $SHORT_SHA

  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"
    }
  }
  
  
  Weitere Informationen zu Secrets in Cloud Build finden Sie in der Cloud Build-Dokumentation unter Secrets aus Secret Manager verwenden.
  
  Ersetzungen Umgebungsvariablen zuordnen
  
  Scripts unterstützen keine direkten Ersetzungen, aber Umgebungsvariablen. Sie können Ersetzungen Umgebungsvariablen zuordnen, entweder automatisch auf einmal oder manuell, indem Sie jede Umgebungsvariable selbst definieren.
  
  Ersetzungen automatisch zuordnen
  
  Auf Build-Ebene: Wenn Sie alle Ersetzungen automatisch Umgebungsvariablen zuordnen möchten, die während des gesamten Builds verfügbar sind, legen Sie automapSubstitutions als Option auf Build-Ebene auf true fest. In der folgenden Build-Konfigurationsdatei sind beispielsweise die benutzerdefinierte Substitution $_USER und die Standardsubstitution $PROJECT_ID Umgebungsvariablen zugeordnet:
  
   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 Ersetzungen automatisch zuordnen und in einem einzigen Schritt als Umgebungsvariablen verfügbar machen möchten, setzen Sie das Feld automapSubstitutions in diesem Schritt auf true. Im folgenden Beispiel werden die Ersetzungen nur im zweiten Schritt korrekt angezeigt, da nur dort die automatische Zuordnung von Ersetzungen 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 Ersetzungen als Umgebungsvariablen im gesamten Build verfügbar machen und sie dann in einem Schritt ignorieren. Legen Sie automapSubstitutions auf Build-Ebene auf true fest und dann im Schritt, in dem Sie die Ersetzungen ignorieren möchten, auf false. Im folgenden Beispiel wird die Projekt-ID im zweiten Schritt nicht ausgegeben, obwohl die Zuordnungssubstitutionen auf Build-Ebene aktiviert sind, da automapSubstitutions in diesem Schritt auf false festgelegt 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"
    }
  
  
  
  Substitutionen manuell zuordnen
  
  Sie können die Ersetzungen manuell Umgebungsvariablen zuordnen. Jede Umgebungsvariable wird auf Schrittebene mit dem Feld env definiert. Der Bereich der Variablen ist auf den Schritt beschränkt, in dem sie definiert sind. Dieses Feld akzeptiert eine Liste von Schlüsseln und Werten.
  
  Im folgenden Beispiel sehen Sie, wie die Ersetzung $PROJECT_ID der Umgebungsvariable 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