Substituting Variable Values

Use substitutions in your build config file to substitute specific variables at runtime. Substitutions are helpful for variables whose value isn't known until build time, or to re-use an existing build request with different variable values.

Cloud Build provides built-in substitutions or you can define your own substitutions. Use the substitutions field in your build's steps and images fields to resolve their values at build time.

This page explains how to use default substitutions or define your own substitutions.

Using default substitutions

Cloud Build provides the following default substitutions:

  • $PROJECT_ID: build.ProjectId
  • $BUILD_ID: build.BuildId
  • $COMMIT_SHA: build.SourceProvenance.ResolvedRepoSource.Revision.CommitSha
  • $SHORT_SHA : The first seven characters of COMMIT_SHA
  • $REPO_NAME: build.Source.RepoSource.RepoName (only available for triggered builds)
  • $BRANCH_NAME: build.Source.RepoSource.Revision.BranchName (only available for triggered builds)
  • $TAG_NAME: build.Source.RepoSource.Revision.TagName (only available for triggered builds)
  • $REVISION_ID: build.SourceProvenance.ResolvedRepoSource.Revision.CommitSha (only available for triggered builds)

If a default substitution is not available (such as with sourceless builds, or with builds that use storage source), then occurrences of the missing variable are replaced with an empty string.

The following example uses the default substitutions $BUILD_ID, $PROJECT_ID, and $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=$PROJECT_ID'
  - '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=$PROJECT_ID",
        "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"
  ]
}

The example below shows a build request using the docker build step to build an image, then pushes the image to Container Registry using the default $PROJECT_ID substitution:

In this example:

  • The build request has one build step, which uses the docker build step in gcr.io/cloud-builders to build the Docker image.
    • The args field in the step specifies the arguments to pass to the docker command, in this case build -t gcr.io/my-project/cb-demo-img ., will be invoked (after $PROJECT_ID is substituted with your project ID).
  • The images field contains the image's name. If the build is successful, the resulting image is pushed to Container Registry. If the image is not created successfully by the build, the build will fail.

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"
  ]
}

Using user-defined substitutions

You can also define your own substitutions. User-defined substitutions must conform to the following rules:

  • Substitutions must begin with an underscore (_) and use only uppercase-letters and numbers (respecting the regular expression _[A-Z0-9_]+). This prevents conflicts with built-in substitutions.
  • Unmatched keys in the template will cause an error (for example, if a build request includes $_FOO and the substitutions map doesn’t define _FOO).
  • Unmatched keys in the parameters list will result in an error (for example, if a substitutions map defines _FOO but the build request doesn't include $_FOO).
  • To include a literal $_VARIABLE in the template, you must escape with $$.
  • You can explicitly denote variable expansion using the ${_VAR} syntax. This prevents ambiguity in cases like ${_FOO}BAR, where $_FOO is a variable.
  • The number of parameters is limited to 100 parameters. The length of a parameter key and the length of a parameter value are limited to 100 characters.

To use the substitutions, use the --substitutions argument in the gcloud command or specify them in the config file.

The following built-in variables can be specified using the --substitutions flag in the gcloud command gcloud builds submit: REPO_NAME, BRANCH_NAME, TAG_NAME, REVISION_ID, COMMIT_SHA, SHORT_SHA.

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',
         '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.5 # 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.5"
    },
    "images": [
        "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
        "gcr.io/$PROJECT_ID/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. The following command overrides the default value for _NODE_VERSION_1 specified in the build config file above:

gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_NODE_VERSION_1=v6.9.4,_NODE_VERSION_2=v9.5.0 .

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Build