変数値の置換

substitutions は、ビルド時に特定の変数を置き換える場合にビルド構成ファイルの中で使用します。

置換はビルド時まで値が不明な変数を設定する場合や、既存のビルドリクエストを別の変数値で再利用する場合に役立ちます。

Cloud Build には組み込みの置換が用意されていますが、独自の置換を定義することもできます。ビルド時に値を解決するには、ビルドの steps と images に substitutions を使用します。

このページでは、デフォルトの置換を使用する方法や独自の substitutions を定義する方法について説明します。

デフォルトの置換の使用

Cloud Build では、すべてのビルドを対象に次のデフォルトの置換が用意されています。

$PROJECT_ID: Cloud プロジェクトの ID
$BUILD_ID: ビルドの ID
$PROJECT_NUMBER: プロジェクトの番号
$LOCATION: ビルドに関連付けられたリージョン

Cloud Build では、トリガーによって呼び出されるビルドを対象に次のデフォルトの置換が用意されています。

$TRIGGER_NAME: トリガーに関連付けられた名前
$COMMIT_SHA: ビルドに関連付けられた commit ID
$REVISION_ID: ビルドに関連付けられた commit ID
$SHORT_SHA: COMMIT_SHA の最初の 7 文字
$REPO_NAME: リポジトリの名前
$BRANCH_NAME: ブランチの名前
$TAG_NAME: タグの名前
$REF_NAME: ブランチまたはタグの名前
$TRIGGER_BUILD_CONFIG_PATH: ビルドの実行中に使用されるビルド構成ファイルへのパス。それ以外の場合は、ビルドがインラインでトリガーに構成された場合、Dockerfile または Buildpack を使用する場合は空の文字列。

Cloud Build では、pull リクエストトリガーに使用する GitHub 固有のデフォルトの置換を以下のように用意しています。

$_HEAD_BRANCH: pull リクエストのヘッドブランチ
$_BASE_BRANCH: pull リクエストのベースブランチ
$_HEAD_REPO_URL: pull リクエストのヘッドリポジトリの URL
$_PR_NUMBER: pull リクエストの数

デフォルトの置換が利用できない場合は（ソースがないビルドや、ストレージソースを使用しているビルドなど）、置換されなかった不明な変数が空の文字列に置き換えられます。

gcloud builds submit を使用してビルドを開始するとき、--substitutions引数を使用して、トリガーされたビルドから通常取得する変数を指定できます。具体的には、次の値を手動で指定できます。

$TRIGGER_NAME
$COMMIT_SHA
$REVISION_ID
$SHORT_SHA
$REPO_NAME
$BRANCH_NAME
$TAG_NAME
$REF_NAME
$TRIGGER_BUILD_CONFIG_PATH

たとえば、次のコマンドでは TAG_NAME 置換を使用しています。

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

次の例では、デフォルトの置換 $BUILD_ID、$PROJECT_ID、$PROJECT_NUMBER、$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_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"
  ]
}

次の例に、docker ビルドステップを使用してイメージを作成し、デフォルトの $PROJECT_ID 置換を使用して Container Registry にイメージを push するビルドリクエストを示します。

この例では、

ビルドリクエストのビルドステップは 1 つで、gcr.io/cloud-builders の docker ビルドステップを使用して Docker イメージをビルドします。
- ステップ内の args フィールドは docker コマンドに渡す引数を指定します。この場合は、build -t gcr.io/my-project/cb-demo-img . が呼び出されます（$PROJECT_ID がプロジェクト ID に置き換えられた後）。
images フィールドにはイメージの名前が含まれます。ビルドが成功すると、ビルドされたイメージは Container Registry に push されます。イメージがビルドによって正常に作成されていない場合、ビルドは失敗します。

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

ユーザー定義の置換の使用

独自の置換を定義することもできます。ユーザー定義の置換は、次のルールに従う必要があります。

置換はアンダースコア（_）で始まり、大文字と数字のみを使用する必要があります（正規表現 _[A-Z0-9_]+ に従います）。こうすると、組み込み置換と競合しなくなります。$ で始まる式を使用するには、$$ を使用する必要があります。つまり、
- $FOO は組み込み置換ではないため、無効です。
- $$FOO はリテラル文字列 $FOO と評価されます。
パラメータの数は 100 パラメータに制限されています。パラメータキーの長さは 100 バイトに、パラメータ値の長さは 4,000 バイトに制限されています。

変数は、$_FOO または ${_FOO} のいずれかで指定できます。

$_FOO と ${_FOO} はどちらも _FOO の値に評価されます。ただし、${} を使用すると、スペースで囲わずに置換を実行できます。これにより、${_FOO}BAR のような置換が可能になります。
$$ では、テンプレートにリテラル $ を含めることができます。つまり、
- $_FOO は _FOO の値と評価されます。
- $$_FOO はリテラル文字列 $_FOO と評価されます。
- $$$_FOO は、_FOO の値が後に続くリテラル文字 $ と評価されます。

置換を使用するには、gcloud コマンドで --substitutions 引数を使用するか、構成ファイルで置換を指定します。

次の例に、_NODE_VERSION_1 と _NODE_VERSION_2 という 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}"
    ]
}

ビルド構成ファイルで指定した置換値をオーバーライドするには、gcloud builds submit コマンドの --substitutions フラグを使用します。置換は、配列やシーケンスではなく、値への変数のマッピングであることに注意してください。$PROJECT_ID と $BUILD_ID 以外のデフォルトの置換変数値をオーバーライドできます。次のコマンドは、上記のビルド構成ファイルで指定されている _NODE_VERSION_1 のデフォルト値をオーバーライドします。

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

デフォルトでは、置換変数や置換がない場合、ビルドでエラーが返されます。ただし、ALLOW_LOOSE オプションを設定すると、このチェックをスキップできます。

次のスニペットは「hello world」を出力し、未使用の置換を定義します。 ALLOW_LOOSE 置換オプションが設定されているため、置換が欠落していてもビルドは成功します。

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

ビルドがトリガーによって呼び出される場合は、デフォルトで ALLOW_LOOSE オプションが設定されます。この場合、置換変数または置換が欠落しているとビルドはエラーを返しません。トリガーによって呼び出されたビルドの ALLOW_LOOSE オプションをオーバーライドすることはできません。

ALLOW_LOOSE オプションを指定しなければ、置換マッピングまたはビルドリクエストに一致しないキーがある場合にエラーが発生します。たとえば、ビルドリクエストに $_FOO が含まれていて、置換マッピングで _FOO が定義されていない場合、ビルドを実行した後またはトリガーが起動した後にトリガーに置換変数が含まれていれば、にエラーが発生します。

以下の置換変数には、ALLOW_LOOSE オプションを設定しなくても、常にデフォルトの空の文字列値が含まれます。

$REPO_NAME
$BRANCH_NAME
$TAG_NAME
$COMMIT_SHA
$SHORT_SHA

置換変数を定義するときは、静的な文字列に制限されません。また、トリガーを呼び出したイベントペイロードにアクセスすることもできます。これらはペイロードバインディングとして使用できます。また、置換変数に bash パラメータの拡張を適用し、結果の文字列を新しい置換変数として保存することもできます。詳しくは、ペイロードバインディングと bash パラメータの拡張を置換で使用するをご覧ください。

動的置換

ビルド構成ファイルで dynamic_substitutions オプションを true に設定すると、ユーザー定義の置換内の別の変数の値を参照できます。トリガーによってビルドが呼び出された場合、dynamic_substitutions フィールドは常に true に設定され、ビルド構成ファイルで指定する必要はありません。ビルドを手動で呼び出す場合、ビルドの実行時に bash パラメータの拡張が解釈されるようにするには、dynamic_substitutions フィールドを true に設定する必要があります。

次のビルド構成ファイルは、変数 ${PROJECT_ID} を参照する置換変数 ${_IMAGE_NAME} を示しています。dynamic_substitutions フィールドは true に設定されているため、参照はビルドを手動で呼び出すときに適用されます。

YAML

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

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

詳細については、bash パラメータの拡張を適用するをご覧ください。

次のステップ

ペイロードバインディングと bash パラメータの拡張を置換で使用する方法を学習する。
基本的なビルド構成ファイルを作成する方法を学習する。
ビルドトリガーを作成および管理する方法を学習する。
Cloud Build でビルドを手動で実行する方法を学習する。