変数値の置換

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: リポジトリの名前
  • $REPO_FULL_NAME: ユーザーまたは組織を含むリポジトリの完全な名前
  • $BRANCH_NAME: ブランチの名前
  • $TAG_NAME: タグの名前
  • $REF_NAME: ブランチまたはタグの名前
  • $TRIGGER_BUILD_CONFIG_PATH: ビルドの実行中に使用されるビルド構成ファイルへのパス。それ以外の場合は、ビルドがインラインでトリガーに構成された場合、Dockerfile または Buildpack を使用する場合は空の文字列。
  • $SERVICE_ACCOUNT_EMAIL: ビルドに使用しているサービス アカウントのメールアドレス。これは、デフォルトのサービス アカウントまたはユーザー指定のサービス アカウントです。
  • $SERVICE_ACCOUNT: サービス アカウントのリソース名。形式は projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL です。

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
  • $REPO_FULL_NAME
  • $BRANCH_NAME
  • $TAG_NAME
  • $REF_NAME
  • $TRIGGER_BUILD_CONFIG_PATH
  • $SERVICE_ACCOUNT_EMAIL
  • $SERVICE_ACCOUNT

たとえば、次のコマンドでは 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 として評価さる $$. Thus:
    • $FOO is invalid since it is not a built-in substitution.
    • $$FOO を使用する必要があります。
  • パラメータの数は 200 パラメータに制限されています。パラメータキーの長さは 100 バイトに、パラメータ値の長さは 4,000 バイトに制限されています。

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

    • $_FOO と ${_FOO} はどちらも _FOO の値に評価されます。ただし、${} を使用すると、スペースで囲わずに置換を実行できます。これにより、${_FOO}BAR のような置換が可能になります。
    • $$ allows you to include a literal $ in the template. Thus:
      • $_FOO evaluates to the value of _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:
    substitutionOption: '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
      • $REPO_FULL_NAME
      • $BRANCH_NAME
      • $TAG_NAME
      • $COMMIT_SHA
      • $SHORT_SHA

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

      動的置換

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

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

      YAML 

      steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
    _IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image'
options:
    dynamicSubstitutions: 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 パラメータの拡張を適用するをご覧ください。

      置換を環境変数にマッピングする

      スクリプトは置換を直接サポートしていませんが、環境変数をサポートしています。置換を環境変数にマッピングすることができます。このマッピングは、一度にすべてを自動で行うことも、すべての環境変数を手動で定義することもできます。

      置換を自動的にマッピングする

      • ビルドレベル。すべての置換を環境変数に自動的にマッピングし、ビルド全体で使用できるようにするには、ビルドレベルでオプションとして automapSubstitutions を true に設定します。たとえば、次のビルド構成ファイルは、環境変数にマッピングされたユーザー定義の置換 $_USER とデフォルトの置換 $PROJECT_ID を示しています。

        YAML 

        steps:
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Hello $_USER"
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Your project ID is $PROJECT_ID"
options:
  automapSubstitutions: true
substitutions:
  _USER: "Google Cloud"

        JSON 

        {
  "steps": [
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
    },
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'"
    }
  ],
  "options": {
    "automap_substitutions": true
  },
  "substitutions": {
    "_USER": "Google Cloud"
  }
}

      • ステップレベル。すべての置換を自動的にマッピングし、1 つのステップで環境変数として使用できるようにするには、対象のステップで automapSubstitutions フィールドを true に設定します。次の例では、自動置換マッピングが有効になっているのは 2 番目のステップのみであるため、このステップのみが置換を正しく表示します。

        YAML 

        steps:
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Hello $_USER"
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Your project ID is $PROJECT_ID"
  automapSubstitutions: true
substitutions:
  _USER: "Google Cloud"

        JSON 

        {
  "steps": [
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
    },
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
      "automap_substitutions": true
    }
  ],
  },
  "substitutions": {
    "_USER": "Google Cloud"
  }

        また、置換をビルド全体で環境変数として利用できるようにしてから、1 つのステップで無視することができます。ビルドレベルで automapSubstitutions を true に設定し、置換を無視するステップで同じフィールドを false に設定します。次の例では、ビルドレベルで置換マッピングが有効になっていますが、2 番目のステップで automapSubstitutions が false に設定されているため、このステップではプロジェクト ID が出力されません。

        YAML 

        steps:
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Hello $_USER"
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Your project ID is $PROJECT_ID"
  automapSubstitutions: false
options:
  automapSubstitutions: true
substitutions:
  _USER: "Google Cloud"

        JSON 

        {
  "steps": [
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
    },
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
      "automap_substitutions": false
    }
  ],
  "options": {
    "automap_substitutions": true
  },
  },
  "substitutions": {
    "_USER": "Google Cloud"
  }

      置換を手動でマッピングする

      置換を環境変数に手動でマッピングできます。すべての環境変数は、env フィールドを使用してステップレベルで定義され、変数のスコープは定義されているステップに制限されます。このフィールドには、キーと値のリストを指定します。

      次の例は、置換 $PROJECT_ID を環境変数 BAR にマッピングする方法を示しています。

      YAML 

      steps:
- name: 'ubuntu'
  env:
  - 'BAR=$PROJECT_ID'
  script: 'echo $BAR'

      JSON 

      {
  "steps": [
    {
      "name": "ubuntu",
      "env": [
        "BAR=$PROJECT_ID"
      ],
      "script": "echo $BAR"
    }
  ]
}

      次のステップ