変数値の置換

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

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

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

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

デフォルトの置換の使用

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

  • $PROJECT_ID: Cloud プロジェクトの ID
  • $BUILD_ID: ビルドの ID

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

  • $COMMIT_SHA: ビルドに関連付けられた commit ID
  • $REVISION_ID: ビルドに関連付けられた commit ID
  • $SHORT_SHA: COMMIT_SHA の最初の 7 文字
  • $REPO_NAME: リポジトリの名前
  • $BRANCH_NAME: ブランチの名前
  • $TAG_NAME: タグの名前

Cloud Build では、pull リクエストに使用できる次の GitHub 固有のデフォルト置換が用意されています。

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

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

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

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

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

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

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

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

この例では、

  • ビルド リクエストのビルドステップは 1 つで、gcr.io/cloud-buildersdocker ビルドステップを使用して 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 が定義されていない場合、ビルドを実行した後またはトリガーが起動した後にトリガーに置換変数が含まれていれば、にエラーが発生します。

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

次のステップ