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 (only available for triggered builds)
  • $SHORT_SHA : The first seven characters of COMMIT_SHA (only available for triggered builds)
  • $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)

Cloud Build also provides the following GitHub-specific default substitutions:

  • HEAD_BRANCH : (pull request only) head branch of the pull request
  • BASE_BRANCH : (pull request only) base branch of the pull request
  • REPO_OWNER : GitHub repository owner

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.

When starting a build using gcloud builds submit, you can specify variables that would normally come from triggered builds with the --substitutions argument. Specifically, you can manually provide values for:

  • $REPO_NAME
  • $BRANCH_NAME
  • $TAG_NAME
  • $REVISION_ID
  • $COMMIT_SHA
  • $SHORT_SHA

For example, the following command uses the TAG_NAME substitution:

gcloud builds submit --config=cloudbuild.yaml \
    --substitutions=TAG_NAME="test"

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).
  • The number of parameters is limited to 255 parameters. The length of a parameter key and the length of a parameter value are limited to 255 characters.

You can define variables in one of three ways: $_FOO, ${_FOO}, or $$_FOO:

  • Both $_FOO and ${_FOO} evaluate to the value of _FOO. However, ${} makes the substitution work without spaces, which allows for substitutions like ${_FOO}BAR.
  • $$_FOO allows you to include a literal variable in the template. That is, $$_FOO evaluates to the literal character $ 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',
         '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}"
    ]
}

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. 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="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:
    substitution_option: 'ALLOW_LOOSE'

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello world"
        ]
    }
    ],
    "substitutions": {
        "_SUB_VALUE": "unused"
},
    "options": {
        "substitution_option": "ALLOW_LOOSE"
    }
}

What's next

Palautteen aihe:

Tämä sivu
Cloud Build