Mengganti nilai variabel

Gunakan substitutions dalam file konfigurasi build untuk mengganti variabel tertentu pada waktu build.

Substitusi berguna untuk variabel yang nilainya tidak diketahui hingga waktu build, atau untuk menggunakan kembali permintaan build yang sudah ada dengan nilai variabel yang berbeda.

Cloud Build menyediakan substitusi bawaan atau Anda dapat menentukan substitusi sendiri. Gunakan substitutions di steps dan images build untuk menyelesaikan nilainya pada waktu build.

Halaman ini menjelaskan cara menggunakan substitusi default atau menentukan substitutions Anda sendiri.

Menggunakan substitusi default

Cloud Build menyediakan substitusi default berikut untuk semua build:

• $PROJECT_ID: ID project Cloud Anda
• $BUILD_ID: ID build Anda
• $PROJECT_NUMBER: nomor project Anda
• $LOCATION: region yang terkait dengan build Anda

Cloud Build menyediakan substitusi default berikut untuk build yang dipanggil oleh pemicu:

• $TRIGGER_NAME: nama yang terkait dengan pemicu Anda
• $COMMIT_SHA: ID commit yang terkait dengan build Anda
• $REVISION_ID: ID commit yang terkait dengan build Anda
• $SHORT_SHA : tujuh karakter pertama dari COMMIT_SHA
• $REPO_NAME: nama repositori Anda
• $REPO_FULL_NAME: nama lengkap repositori Anda, termasuk pengguna atau organisasi
• $BRANCH_NAME: nama cabang Anda
• $TAG_NAME: nama tag Anda
• $REF_NAME: nama cabang atau tag Anda
• $TRIGGER_BUILD_CONFIG_PATH: jalur ke file konfigurasi build yang digunakan selama eksekusi build; jika tidak, string kosong jika build Anda dikonfigurasi inline pada pemicu atau menggunakan Dockerfile atau Buildpack.
• $SERVICE_ACCOUNT_EMAIL: email akun layanan yang Anda gunakan untuk build. Ini adalah akun layanan default atau akun layanan yang ditentukan pengguna.
• $SERVICE_ACCOUNT: nama resource akun layanan, dalam format projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

Catatan: $COMMIT_SHA dan $REVISION_ID mewakili ID commit yang terkait dengan build Anda. Dukungan untuk kedua substitusi tersedia.

Cloud Build menyediakan substitusi default khusus GitHub berikut yang tersedia untuk pemicu permintaan pull:

• $_HEAD_BRANCH : cabang utama permintaan pull
• $_BASE_BRANCH : cabang dasar permintaan pull
• $_HEAD_REPO_URL : URL repositori utama permintaan pull
• $_PR_NUMBER : nomor permintaan pull

Jika substitusi default tidak tersedia (seperti pada build tanpa sumber, atau dengan build yang menggunakan sumber penyimpanan), kemunculan variabel yang tidak ada akan diganti dengan string kosong.

Saat memulai build menggunakan gcloud builds submit, Anda dapat menentukan variabel yang biasanya berasal dari build yang dipicu dengan argumen --substitutions. Secara khusus, Anda dapat memberikan nilai secara manual untuk:

• $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

Misalnya, perintah berikut menggunakan substitusi TAG_NAME:

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

Contoh berikut menggunakan substitusi default $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER, dan $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', '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/my-image', '.']

# my-image is pushed to Artifact Registry
images:
- '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/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"
  ]
}

Contoh berikut menunjukkan permintaan build menggunakan langkah build docker untuk membangun image, lalu mengirim image ke Artifact Registry menggunakan substitusi $PROJECT_ID default:

Dalam contoh ini:

• Permintaan build memiliki satu langkah build, yang menggunakan langkah build docker di gcr.io/cloud-builders untuk membangun image Docker.
  • Kolom args dalam langkah ini menentukan argumen yang akan diteruskan ke perintah docker, dalam hal ini build -t gcr.io/my-project/cb-demo-img ., akan dipanggil (setelah $PROJECT_ID diganti dengan project ID Anda).

• Kolom images berisi nama image. Jika build berhasil, image yang dihasilkan akan dikirim ke Artifact Registry. Jika image tidak berhasil dibuat oleh build, build akan gagal.

YAML

steps:
- name: gcr.io/cloud-builders/docker
  args: ["build", "-t", "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img", "."]
images:
- '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img'

JSON

{
  "steps": [{
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img", "."]
    }],
  "images": [
    "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img"
  ]
}

Menggunakan substitusi buatan pengguna

Anda juga dapat menentukan substitusi sendiri. Substitusi buatan pengguna harus mematuhi aturan berikut:

• Substitusi harus dimulai dengan garis bawah (_) dan hanya menggunakan huruf besar dan angka (mematuhi ekspresi reguler _[A-Z0-9_]+). Hal ini mencegah konflik dengan substitusi bawaan. Untuk menggunakan ekspresi yang dimulai dengan $ Anda harus menggunakan $$. For example:
  • $FOO is invalid since it is not a built-in substitution.
  • $$FOO yang dievaluasi ke string literal $FOO.
• Jumlah parameter dibatasi hingga 200 parameter. Panjang kunci parameter dibatasi hingga 100 byte dan panjang nilai parameter dibatasi hingga 4.000 byte.

Anda dapat menentukan variabel dengan salah satu dari dua cara: $_FOO atau ${_FOO}:

• Both $_FOO and ${_FOO} dievaluasi ke nilai _FOO. Namun, ${} memungkinkan substitusi berfungsi tanpa spasi di sekitarnya, yang memungkinkan substitusi seperti ${_FOO}BAR.
• $$ lets you include a literal $ in the template. For example:
  • $_FOO evaluates to the value of _FOO.
  • $$_FOO dievaluasi ke string literal $_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',
          '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}',
          '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
          '--build-arg',
          'node_version=${_NODE_VERSION_2}',
          '-t',
          '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}',
          '.']
substitutions:
    _NODE_VERSION_1: v6.9.1 # default value
    _NODE_VERSION_2: v6.9.2 # default value
images: [
    '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}',
    '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}'
]

JSON

{
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_1}",
            "-t",
            "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}",
            "."
        ]
    }, {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_2}",
            "-t",
            "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}",
            "."
        ]
    }],
    "substitutions": {
        "_NODE_VERSION_1": "v6.9.1",
        "_NODE_VERSION_2": "v6.9.2",
    },
    "images": [
        "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}",
        "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/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 previous build config file:

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:
    substitutionOption: '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 won't 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.

The following substitution variables always contain a default empty-string value even if you don't set the ALLOW_LOOSE option:

• $REPO_NAME
• $REPO_FULL_NAME
• $BRANCH_NAME
• $TAG_NAME
• $COMMIT_SHA
• $SHORT_SHA

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

Dynamic substitutions

You can reference the value of another variable within a user-defined substitution by setting the dynamicSubstitutions option to true in your build config file. If your build is invoked by a trigger, the dynamicSubstitutions field is always set to true and does not need to be specified in your build config file. If your build is invoked manually, you must set the dynamicSubstitutions field to true for bash parameter expansions to be interpreted when running your build.

The following build config file shows the substitution variable ${_IMAGE_NAME} referencing the variable, ${PROJECT_ID}. The dynamicSubstitutions field is set to true so the reference is applied when invoking a build manually:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
    _IMAGE_NAME: '${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPOSITORY}/test-image'
options:
    dynamicSubstitutions: true

JSON

{
    "steps": [
      {
          "name": "gcr.io/cloud-builders/docker",
          "args": [
            "build",
            "-t",
            "${_IMAGE_NAME}",
            "."
          ]
      }
    ],
    "substitutions": {
      "_IMAGE_NAME": "${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPOSITORY}/test-image"
    },
    "options": {
      "dynamic_substitutions": true
    }
}

For more information, see Applying bash parameter expansions.

Secret substitutions

You can substitute secrets from Secret Manager in Cloud Build. To do so, include your substitution variable in the value of the versionName field in your build config file.

The following example shows how to define a substitution for a secret version.

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: 'bash'
  args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
  secretEnv: ['USERNAME', 'PASSWORD']

availableSecrets:
  secretManager:
  - versionName: projects/$PROJECT_ID/secrets/my-docker-password/versions/$_SECRET_VERSION
    env: 'PASSWORD'
  - versionName: projects/$PROJECT_ID/secrets/my-docker-username/versions/latest
    env: 'USERNAME'

substitutions:
    _SECRET_VERSION: '1' #Default value for the secret version

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "entrypoint": "bash",
      "args": [
        "-c",
        "docker login --username=$$USERNAME --password=$$PASSWORD"
      ],
      "secretEnv": [
        "USERNAME",
        "PASSWORD"
      ]
    }
  ],
  "availableSecrets": {
    "secretManager": [
      {
        "versionName": "projects/$PROJECT_ID/secrets/my-docker-password/versions/$_SECRET_VERSION",
        "env": "PASSWORD"
      },
      {
        "versionName": "projects/$PROJECT_ID/secrets/my-docker-username/versions/latest",
        "env": "USERNAME"
      }
    ]
  },
  "substitutions": {
    "_SECRET_VERSION": "1"
  }
}


Untuk mengetahui informasi selengkapnya tentang secret di Cloud Build, lihat
Menggunakan secret dari Secret Manager
dalam dokumentasi Cloud Build.

Memetakan substitusi ke variabel lingkungan

Skrip tidak secara langsung mendukung substitusi, tetapi mendukung variabel lingkungan. Anda dapat memetakan substitusi ke variabel lingkungan, baik secara otomatis sekaligus, atau secara manual dengan menentukan setiap variabel lingkungan sendiri.

Memetakan substitusi secara otomatis

Di tingkat build. Untuk memetakan semua substitusi ke variabel lingkungan secara otomatis, yang akan tersedia di seluruh build, tetapkan automapSubstitutions ke true sebagai opsi di tingkat build. Misalnya, file konfigurasi build berikut menunjukkan substitusi buatan pengguna $_USER dan substitusi default $PROJECT_ID yang dipetakan ke variabel lingkungan:

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


Di tingkat langkah. Untuk memetakan semua substitusi secara otomatis dan membuatnya tersedia sebagai variabel lingkungan dalam satu langkah, tetapkan kolom automapSubstitutions ke true dalam langkah tersebut. Dalam contoh berikut, hanya langkah kedua yang akan menampilkan substitusi dengan benar, karena hanya langkah kedua yang mengaktifkan pemetaan substitusi otomatis:

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


Selain itu, Anda dapat membuat substitusi tersedia sebagai variabel lingkungan di seluruh build, lalu mengabaikannya dalam satu langkah. Tetapkan automapSubstitutions ke true di tingkat build, lalu tetapkan kolom yang sama ke false di langkah tempat Anda ingin mengabaikan substitusi. Dalam contoh berikut, meskipun substitusi pemetaan diaktifkan di tingkat build, project ID tidak akan dicetak pada langkah kedua, karena automapSubstitutions ditetapkan ke false pada langkah tersebut:

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



Memetakan substitusi secara manual

Anda dapat memetakan substitusi ke variabel lingkungan secara manual. Setiap
variabel lingkungan ditentukan di tingkat langkah menggunakan kolom env, dan cakupan variabel dibatasi ke langkah
tempat variabel tersebut ditentukan. Kolom ini mengambil daftar kunci dan nilai.

Contoh berikut menunjukkan cara memetakan substitusi $PROJECT_ID ke variabel lingkungan BAR:

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

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


Langkah berikutnya


Pelajari cara menggunakan binding payload dan ekspansi parameter bash dalam substitusi.
Pelajari cara membuat file konfigurasi build dasar.
Pelajari cara membuat dan mengelola pemicu build.
Pelajari cara menjalankan build secara manual di Cloud Build.