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 penggantian bawaan atau Anda dapat menentukan penggantian Anda sendiri. Gunakan substitutions di steps dan images build Anda untuk me-resolve nilainya pada waktu build.

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

Menggunakan penggantian default

Cloud Build menyediakan penggantian 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 penggantian 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 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 secara 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 penggantian tersebut tersedia.

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

• $_HEAD_BRANCH : cabang head permintaan pull
• $_BASE_BRANCH : cabang dasar permintaan pull
• $_HEAD_REPO_URL : URL repo head permintaan pull
• $_PR_NUMBER : jumlah permintaan pull

Jika penggantian default tidak tersedia (seperti dengan build tanpa sumber, atau dengan build yang menggunakan sumber penyimpanan), kemunculan variabel yang hilang 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 penggantian TAG_NAME:

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

Contoh berikut menggunakan penggantian 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', '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"
  ]
}

Contoh di bawah menunjukkan permintaan build menggunakan langkah build docker untuk mem-build image, lalu mengirimkan image ke Container Registry menggunakan penggantian $PROJECT_ID default:

Dalam contoh ini:

• Permintaan build memiliki satu langkah build, yang menggunakan langkah build docker di gcr.io/cloud-builders untuk mem-build image Docker.
  • Kolom args dalam langkah 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 gambar. Jika build berhasil, image yang dihasilkan akan di-push ke Container Registry. Jika image tidak berhasil dibuat oleh build, build akan gagal.

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

Menggunakan penggantian yang ditentukan pengguna

Anda juga dapat menentukan penggantian Anda sendiri. Penggantian yang ditentukan pengguna harus sesuai dengan aturan berikut:

• Substitusi harus dimulai dengan garis bawah (_) dan hanya menggunakan huruf besar dan angka (mengikuti ekspresi reguler _[A-Z0-9_]+). Hal ini mencegah konflik dengan substitusi bawaan. Untuk menggunakan ekspresi yang dimulai dengan $, Anda harus menggunakan $$. Thus:
  • $FOO is invalid since it is not a built-in substitution.
  • $$FOO yang dievaluasi menjadi 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}:

• $_FOO dan ${_FOO} dievaluasi ke nilai _FOO. Namun, ${} memungkinkan penggantian berfungsi tanpa spasi di sekitarnya, yang memungkinkan penggantian seperti ${_FOO}BAR.
• $$ allows you to include a literal $ in the template. Thus:
  • $_FOO evaluates to the value of _FOO.
  • $$_FOO dievaluasi menjadi string literal $_FOO.
  • $$$_FOO dievaluasi menjadi string literal $, diikuti dengan nilai _FOO.

  Untuk menggunakan penggantian, gunakan argumen --substitutions dalam perintah gcloud atau tentukan dalam file konfigurasi.

  Contoh berikut menunjukkan konfigurasi build dengan dua penggantian yang ditentukan pengguna yang disebut _NODE_VERSION_1 dan _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}"
      ]
  }
  

  Untuk mengganti nilai penggantian yang Anda tentukan dalam file konfigurasi build, gunakan tanda --substitutions dalam perintah gcloud builds submit. Perhatikan bahwa penggantian adalah pemetaan variabel ke nilai, bukan array atau urutan. Anda dapat mengganti nilai variabel penggantian default kecuali untuk $PROJECT_ID dan $BUILD_ID. Perintah berikut mengganti nilai default untuk _NODE_VERSION_1 yang ditentukan dalam file konfigurasi build di atas:

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

  Secara default, build menampilkan error jika ada variabel penggantian yang hilang atau penggantian yang hilang. Namun, Anda dapat menetapkan opsi ALLOW_LOOSE untuk melewati pemeriksaan ini.

  Cuplikan berikut mencetak "hello world" dan menentukan penggantian yang tidak digunakan. Karena opsi penggantian ALLOW_LOOSE ditetapkan, build akan berhasil meskipun penggantian tidak ada.

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

  Jika build Anda dipanggil oleh pemicu, opsi ALLOW_LOOSE akan ditetapkan secara default. Dalam hal ini, build Anda tidak akan menampilkan error jika ada variabel penggantian yang hilang atau penggantian yang hilang. Anda tidak dapat mengganti opsi ALLOW_LOOSE untuk build yang dipanggil oleh pemicu.

  Jika opsi ALLOW_LOOSE tidak ditentukan, kunci yang tidak cocok dalam pemetaan penggantian atau permintaan build akan menyebabkan error. Misalnya, jika permintaan build Anda menyertakan $_FOO dan pemetaan penggantian tidak menentukan _FOO, Anda akan menerima error setelah menjalankan build atau memanggil pemicu jika pemicu menyertakan variabel penggantian.

  Variabel penggantian berikut selalu berisi nilai string kosong default meskipun Anda tidak menetapkan opsi ALLOW_LOOSE:

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

  Saat menentukan variabel penggantian, Anda tidak terbatas pada string statis. Anda juga memiliki akses ke payload peristiwa yang memanggil pemicu. Ini tersedia sebagai binding payload. Anda juga dapat menerapkan ekspansi parameter bash pada variabel penggantian dan menyimpan string yang dihasilkan sebagai variabel penggantian baru. Untuk mempelajari lebih lanjut, lihat Menggunakan binding payload dan ekspansi parameter bash dalam substitusi.

  Penggantian dinamis

  Anda dapat mereferensikan nilai variabel lain dalam penggantian yang ditentukan pengguna dengan menetapkan opsi dynamicSubstitutions ke true dalam file konfigurasi build. Jika build Anda dipanggil oleh pemicu, kolom dynamicSubstitutions selalu ditetapkan ke true dan tidak perlu ditentukan dalam file konfigurasi build Anda. Jika build dipanggil secara manual, Anda harus menetapkan kolom dynamicSubstitutions ke true agar perluasan parameter bash ditafsirkan saat menjalankan build.

  File konfigurasi build berikut menunjukkan variabel penggantian ${_IMAGE_NAME} yang mereferensikan variabel, ${PROJECT_ID}. Kolom dynamicSubstitutions ditetapkan ke true sehingga referensi diterapkan saat memanggil build secara manual:

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

  Untuk informasi selengkapnya, lihat Menerapkan perluasan parameter bash.

  Memetakan penggantian ke variabel lingkungan

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

  Memetakan penggantian secara otomatis

  • Di tingkat build. Untuk memetakan semua penggantian 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 penggantian yang ditentukan pengguna $_USER dan penggantian 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 penggantian secara otomatis dan membuatnya tersedia sebagai variabel lingkungan dalam satu langkah, tetapkan kolom automapSubstitutions ke true pada langkah tersebut. Dalam contoh berikut, hanya langkah kedua yang akan menampilkan penggantian dengan benar, karena ini adalah satu-satunya langkah yang mengaktifkan pemetaan penggantian 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 menyediakan penggantian 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 pada langkah tempat Anda ingin mengabaikan penggantian. Dalam contoh berikut, meskipun penggantian 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 penggantian secara manual

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

  Contoh berikut menunjukkan cara memetakan penggantian $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 selanjutnya

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