Substituting variable values

Use substitutions in your build config file to substitute specific variables at build time.

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 substitutions in your build's steps and images 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 for all builds:

  • $PROJECT_ID: ID of your Cloud project
  • $BUILD_ID: ID of your build

Cloud Build provides the following default substitutions for builds invoked by triggers:

  • $COMMIT_SHA: the commit ID associated with your build
  • $REVISION_ID: the commit ID associated with your build.
  • $SHORT_SHA : the first seven characters of COMMIT_SHA
  • $REPO_NAME: the name of your repository
  • $BRANCH_NAME: the name of your branch
  • $TAG_NAME: the name of your tag

Cloud Build provides the following GitHub-specific default substitutions available for pull requests:

  • $_HEAD_BRANCH : head branch of the pull request
  • $_BASE_BRANCH : base branch of the pull request
  • $_HEAD_REPO_URL : url of the head repo of the pull request
  • $_PR_NUMBER : number of the pull request

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:

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

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. To use an expression starting with $ you must use $$. Thus:
    • $FOO is invalid since it not a built-in substitution.
    • $$FOO evaluates to the literal string $FOO.
  • The number of parameters is limited to 100 parameters. The length of a parameter key is limited to 100 bytes and the length of a parameter value is limited to 4000 bytes.

You can specify variables in one of two ways: $_FOO or ${_FOO}:

  • Both $_FOO and ${_FOO} evaluate to the value of _FOO. However, ${} lets the substitution work without surrounding spaces, which allows for substitutions like ${_FOO}BAR.
  • $$ allows you to include a literal $ in the template. Thus:
    • $_FOO evaluates to the value of _FOO.
    • $$_FOO evaluates to the literal string $_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',
         '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. 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 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"
    }
}

If your build is invoked by a trigger, the ALLOW_LOOSE option is set by default. In this case, your build will not 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.

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-style string operations on substitution variables and store the resulting string as a new substitution variable. To learn more, see Using bash-style string operations and payload bindings in substitutions.

What's next