Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

建構設定檔結構定義

建構設定檔包含 Cloud Build 依據您的規格執行工作的操作說明。舉例來說，建構設定檔可以包含建構、封裝及推送 Docker 映像檔的操作說明。

本頁面說明 Cloud Build 設定檔的結構定義。如需建立及使用建構設定檔的操作說明，請參閱「建立基本建構設定檔」。

建構設定檔的結構

建構設定檔是使用 Cloud Build API 的 Build 資源建立模型。

您可以使用 YAML 或 JSON 語法編寫建構設定檔。如果您使用 curl 等第三方 HTTP 工具提交建構要求，請使用 JSON 語法。

建構設定檔的結構如下：

YAML

steps:
- name: string
  args: [string, string, ...]
  env: [string, string, ...]
  allowFailure: boolean
  allowExitCodes: [string (int64 format), string (int64 format), ...]
  dir: string
  id: string
  waitFor: [string, string, ...]
  entrypoint: string
  secretEnv: string
  volumes: object(Volume)
  timeout: string (Duration format)
  script: string
  automapSubstitutions: boolean
  results: object(Results)
- name: string
  ...
- name: string
  ...
timeout: string (Duration format)
queueTtl: string (Duration format)
logsBucket: string
options:
 env: [string, string, ...]
 secretEnv: string
 volumes: object(Volume)
 sourceProvenanceHash: enum(HashType)
 machineType: enum(MachineType)
 diskSizeGb: string (int64 format)
 substitutionOption: enum(SubstitutionOption)
 dynamicSubstitutions: boolean
 automapSubstitutions: boolean
 logStreamingOption: enum(LogStreamingOption)
 logging: enum(LoggingMode)
 defaultLogsBucketBehavior: enum(DefaultLogsBucketBehavior)
 pool: object(PoolOption)
 pubsubTopic: string
 requestedVerifyOption: enum(RequestedVerifyOption)
 workerRelease: string
substitutions: map (key: string, value: string)
tags: [string, string, ...]
serviceAccount: string
secrets: object(Secret)
availableSecrets: object(Secrets)
artifacts: object(Artifacts)
  goModules: [object(GoModules), ...]
  mavenArtifacts: [object(MavenArtifact), ...]
  pythonPackages: [object(PythonPackage), ...]
  npmPackages: [object(npmPackage), ...]
images:
- [string, string, ...]

JSON

{
    "steps": [
    {
        "name": "string",
        "args": [
            "string",
            "string",
            "..."
        ],
        "env": [
            "string",
            "string",
            "..."
        ],
        "allowFailure": "boolean",
        "allowExitCodes: [
            "string (int64 format)",
            "string (int64 format)",
            "..."
        ],
        "dir": "string",
        "id": "string",
        "waitFor": [
            "string",
            "string",
            "..."
        ],
        "entrypoint": "string",
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "timeout": "string (Duration format)",
        "script" : "string",
        "automapSubstitutions" : "boolean",
        "results": "object(Results)"
    },
    {
        "name": "string"
        ...
    },
    {
        "name": "string"
        ...
    }
    ],
    "timeout": "string (Duration format)",
    "queueTtl": "string (Duration format)",
    "logsBucket": "string",
    "options": {
        "sourceProvenanceHash": "enum(HashType)",
        "machineType": "enum(MachineType)",
        "diskSizeGb": "string (int64 format)",
        "substitutionOption": "enum(SubstitutionOption)",
        "dynamicSubstitutions": "boolean",
        "automapSubstitutions": "boolean",
        "logStreamingOption": "enum(LogStreamingOption)",
        "logging": "enum(LoggingMode)",
        "defaultLogsBucketBehavior": "enum(DefaultLogsBucketBehavior)"
        "env": [
            "string",
            "string",
            "..."
        ],
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "pool": "object(PoolOption)",
        "pubsubTopic: string",
        "requestedVerifyOption": "enum(RequestedVerifyOption)",
        "workerRelease": "string"
    },
    "substitutions": "map (key: string, value: string)",
    "tags": [
        "string",
        "string",
        "..."
    ],
    "serviceAccount": "string",
    "secrets": "object(Secret)",
    "availableSecrets": "object(Secrets)",
    "artifacts": "object(Artifacts)",
      "goModules": [object(GoModules), ...],
      "mavenArtifacts": ["object(MavenArtifact)", ...],
      "pythonPackages": ["object(PythonPackage)", ...],
      "npmPackages": ["object(npmPackage)", ...],
    "images": [
        "string",
        "string",
        "..."
    ]
}

建構設定檔的每個區段都定義您想讓 Cloud Build 執行的一部分工作：

建構步驟

建構步驟指定您想讓 Cloud Build 執行的動作。針對每個建構步驟，Cloud Build 會執行 Docker 容器，做為 docker run 的執行個體。建構步驟與指令碼中的指令類似，可讓您在建構中靈活執行任意操作說明。只要能將建構工具封裝至容器，Cloud Build 就能在建構過程中執行該工具。根據預設，Cloud Build 會在同一部機器上，依序執行建構作業的所有步驟。如果有些步驟可以同時執行，請使用 waitFor 選項。

設定檔最多可包含 300 個建構步驟。

使用建構設定檔中的 steps 欄位指定建構步驟。以下是您可能在 steps 欄位中設定的設定類型程式碼片段：

YAML

steps:
- name: 'gcr.io/cloud-builders/kubectl'
  args: ['set', 'image', 'deployment/mydepl', 'my-image=gcr.io/my-project/myimage']
  env:
  - 'CLOUDSDK_COMPUTE_ZONE=us-east4-b'
  - 'CLOUDSDK_CONTAINER_CLUSTER=my-cluster'
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/kubectl",
        "args": [
            "set",
            "image"
            "deployment/mydepl"
            "my-image=gcr.io/my-project/myimage"
        ],
        "env": [
            "CLOUDSDK_COMPUTE_ZONE=us-east4-b",
            "CLOUDSDK_CONTAINER_CLUSTER=my-cluster"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

`name`

使用建構步驟的 name 欄位指定雲端建構工具，也就是執行常見工具的容器映像檔。您可以在建構步驟中使用建構工具來執行您的工作。

下列程式碼片段顯示呼叫 bazel、gcloud 和 docker 建構工具的建構步驟：

YAML

steps:
- name: 'gcr.io/cloud-builders/bazel'
...

- name: 'gcr.io/cloud-builders/gcloud'
...

- name: 'gcr.io/cloud-builders/docker'
...

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/bazel"
        ...
    },
    {
        "name": "gcr.io/cloud-builders/gcloud"
        ...
    },
    {
        "name": "gcr.io/cloud-builders/docker"
        ...
    }
    ]
}

`args`

建構步驟的 args 欄位會接收引數清單，並將引數傳遞至 name 欄位參照的建構工具。傳遞至建構工具的引數會傳遞至建構工具中執行的工具，讓您叫用工具支援的任何指令。如果建構步驟中使用的建構工具擁有進入點，系統會將 args 做為該進入點的引數使用。如果建構工具並未定義進入點，系統會將 args 中的第一個元素做為進入點使用，並將其餘元素做為引數使用。

每個步驟最多可建立 100 個引數。引數長度上限為 10,000 個字元。

下列程式碼片段會叫用 docker build 指令，並安裝 Maven 依附元件：

YAML

steps:
- name: 'gcr.io/cloud-builders/mvn'
  args: ['install']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/mvn",
        "args": [
            "install"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

`env`

建構步驟的 env 欄位會列出執行步驟時要使用的環境變數。變數格式為 KEY=VALUE。

在下列建構設定中，建構步驟的 env 欄位會在執行 kubectl 之前，設定 Compute Engine 區域和 GKE 叢集：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
- name: 'gcr.io/cloud-builders/kubectl'
  args: ['set', 'image', 'deployment/myimage', 'frontend=gcr.io/myproject/myimage']
  env:
  - 'CLOUDSDK_COMPUTE_ZONE=us-east1-b'
  - 'CLOUDSDK_CONTAINER_CLUSTER=node-example-cluster'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    },
    {
        "name": "gcr.io/cloud-builders/kubectl",
        "args": [
            "set",
            "image",
            "deployment/myimage",
            "frontend=gcr.io/myproject/myimage"
        ],
        "env": [
            "CLOUDSDK_COMPUTE_ZONE=us-east1-b",
            "CLOUDSDK_CONTAINER_CLUSTER=node-example-cluster"
        ]
    }
    ]
}

`allowFailure`

在建構步驟中，如果您將 allowFailure 欄位的值設為 true，且建構步驟失敗，則只要該建構中的所有其他建構步驟成功，建構就會成功。

如果建構作業中的所有建構步驟都將 allowFailure 設為 true，且所有建構步驟都失敗，則建構作業的狀態仍為 Successful。

allowExitCodes 的優先順序高於這個欄位。

下列程式碼片段可讓建構作業在第一步失敗時成功：

YAML

steps:
- name: 'ubuntu'
  args: [ '-c', 'exit 1']
  allowFailure: true
- name: 'ubuntu'
  args: ['echo', 'Hello World']

JSON

{
  "steps": [
    {
        "name": "ubuntu",
        "args": [
            "-c",
            "exit -1"
        ],
        "allowFailure": true,
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "Hello World"
        ]
    }
  ]
}

`allowExitCodes`

使用 allowExitCodes 欄位，指定當建構步驟傳回特定結束代碼時，可以忽略該步驟失敗。

如果建構步驟失敗，且結束代碼與您在 allowExitCodes 中提供的值相符，Cloud Build 會允許該建構步驟失敗，而不會導致整個建構作業失敗。

如果建構步驟 100% 失敗，但每個步驟都以您在 allowExitCodes 欄位中指定的代碼結束，則建構作業仍會成功。

不過，如果建構步驟失敗，並產生其他退出代碼 (與您在 allowExitCodes 中指定的值不符)，則整體建構作業會失敗。

與建構作業相關的結束代碼取決於軟體。舉例來說，「1」是 Linux 中常見的結束代碼。您也可以在指令碼中定義自己的結束代碼。allowExitCodes 欄位接受的數字上限為 255。

這個欄位的優先順序高於 allowFailure。

下列程式碼片段可讓建構作業在第一個步驟失敗時，使用其中一個提供的結束代碼成功執行：

YAML

steps:
- name: 'ubuntu'
  args: ['-c', 'exit 1']
  allowExitCodes: [1]
- name: 'ubuntu'
  args: ['echo', 'Hello World']

JSON

{
  "steps": [
    {
        "name": "ubuntu",
        "args": [
            "-c",
            "exit 1"
        ],
        "allowExitCodes": [1],
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "Hello World"
        ]
    }
  ]
}

`dir`

在建構步驟中使用 dir 欄位，設定執行步驟容器時要使用的目前使用的目錄。如果您在建構步驟中設定 dir 欄位，目前使用的目錄會設為 /workspace/<dir>。如果這個值是相對路徑，則會相對於建構作業目前使用的目錄。如果這個值是絕對值，則可能位於建構作業目前使用的目錄之外，在這種情況下，路徑內容可能不會在建構步驟執行期間保留 (除非指定該路徑的磁碟區)。

下列程式碼片段會將建構步驟的目前使用的目錄設為 /workspace/examples/hello_world：

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
  env: ['PROJECT_ROOT=hello']
  dir: 'examples/hello_world'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ],
        "env": [
            "PROJECT_ROOT=hello"
        ],
        "dir": "examples/hello_world"
    }
    ]
}

ID

使用 id 欄位，為建構步驟設定專屬 ID。id 會與 waitFor 欄位搭配使用，設定建構步驟的執行順序。如需使用 waitFor 和 id 的操作說明，請參閱「設定建構步驟順序」。

`waitFor`

在建構步驟中使用 waitFor 欄位，指定哪些步驟必須在建構步驟執行前執行。如果未提供 waitFor 的值，建構步驟會等待建構要求中的所有先前建構步驟成功完成，然後再執行。如需使用 waitFor 和 id 的操作說明，請參閱「設定建構步驟順序」。

`entrypoint`

如果您不想使用建構工具的預設進入點，請在建構步驟中使用 entrypoint 指定進入點。如果您並未設定這個欄位，Cloud Build 會使用建構工具的進入點。下列程式碼片段會設定 npm 建構步驟的進入點：

YAML

steps:
- name: 'gcr.io/cloud-builders/npm'
  entrypoint: 'node'
  args: ['--version']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/npm",
        "entrypoint": "node",
        "args": [
            "--version"
        ]
    }
    ]
}

`secretEnv`

這是使用 Cloud KMS 加密編譯金鑰加密的環境變數清單。這些值必須在建構的密碼中指定。如要瞭解如何使用這個欄位，請參閱在建構要求中使用加密的變數一文。

`volumes`

Volume 是掛接至建構步驟的 Docker 容器磁碟區，用於在建構步驟之間保留檔案。Cloud Build 執行建構步驟時，會自動將 workspace 磁碟區掛接至 /workspace。您可以使用步驟的 volumes 欄位，指定要掛接至建構步驟容器的其他磁碟區。

例如，下面的建構設定檔會在第一個步驟中將檔案寫入磁碟區，並在第二個步驟中讀取該檔案。如果這些步驟未將 /persistent_volume 路徑指定為永久磁碟區，則第一個步驟會在該路徑寫入檔案，然後在執行第二個步驟之前捨棄該檔案。在兩個步驟中指定相同名稱的磁碟區，即可將第一個步驟中 /persistent_volume 的內容保留到第二個步驟。

YAML

steps:
- name: 'ubuntu'
  volumes:
  - name: 'vol1'
    path: '/persistent_volume'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
        echo "Hello, world!" > /persistent_volume/file
- name: 'ubuntu'
  volumes:
  - name: 'vol1'
    path: '/persistent_volume'
  args: ['cat', '/persistent_volume/file']

JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "volumes": [
          {
            "name": "vol1",
            "path": "/persistent_volume"
          }
        ],
        "entrypoint": "bash",
        "args": [
          "-c",
          "echo \"Hello, world!\" > /persistent_volume/file\n"
        ]
      },
      {
        "name": "ubuntu",
        "volumes": [
          {
            "name": "vol1",
            "path": "/persistent_volume"
          }
        ],
        "args": [
          "cat",
          "/persistent_volume/file"
        ]
     }
    ]
  }

`timeout`

在建構步驟中使用 timeout 欄位，設定執行步驟的時間限制。如未設定這個欄位，步驟會持續執行，直到完成或建構作業本身逾時為止。建構步驟的 timeout 欄位不得超過為建構指定的 timeout 值。

timeout 的單位為秒 (使用時間長度格式)，最多可有九個小數位數，結尾為 s (例如：3.5s)。

在下列建構設定中，ubuntu 步驟會在 500 秒後逾時：

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '600']
  timeout: 500s
- name: 'ubuntu'
  args: ['echo', 'hello world, after 600s']

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "600"
        ],
        "timeout": "500s"
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello world, after 600s"
        ]
    }
    ]
}

script

在建構步驟中使用 script 欄位，指定要在步驟中執行的殼層指令碼。如果您在建構步驟中指定 script，就無法在同一步驟中指定 args 或 entrypoint。如需使用 script 欄位的操作說明，請參閱「執行 Bash 指令碼」。

automapSubstitutions

如果設為 true，系統會自動對應所有替代項目，並在單一步驟中將其設為環境變數。如果設為 false，則會忽略該步驟的替代項目。如需範例，請參閱「替換變數值」。

結果

允許建構步驟儲存資料，並在建構完成後，將該資料附加至建構結果的認證中。儲存的資料必須是鍵/值組合，其中鍵是字串，值是 JSON 物件。結果必須包含下列欄位：

name：結果名稱。這個名稱會顯示在建構結果的認證中。您也可以使用這個名稱，在建構步驟中參照結果。例如，您可以在同一個建構步驟中使用 script，將值附加至結果。
attestationContent：(選用) 認證名稱。這可以是任何值，並會顯示在建構結果中的認證。只有在您打算驗證建構認證時，才需要這個欄位。
attestationType：(選用) 認證類型。這可以是任何值，並會顯示在建構結果中的認證。只有在您打算驗證建構認證時，才需要這個欄位。

下列建構作業會使用結果設定輸出認證，讓使用者驗證建構作業是否僅使用具有支援前置字元的網址來建構映像檔。在本範例中，結果定義為 allowlisted_prefixes。接著，allowlisted_prefixes 會設為 allowlisted_prefixes 和 [\"github.com\", \"gitlab.com\"] 的鍵/值組合，然後做為認證附加至建構結果。

YAML

steps:
- name: "gcr.io/cloud-builders/docker"
  id: "build-step"
  args: ["build", "-t", "us-docker.pkg.dev/my-project/demo/helloworld-image", "."]
- name: "ubuntu"
  id: "check-source-fetch-urls"
  results:
    - name: "allowlisted_prefixes"
      attestationContent: "remote_fetch_allow_list"
      attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions"
  script: |
    #!/bin/bash
    prefixes="[\"github.com\", \"gitlab.com\"]"
    echo "allowlisted_prefixes=$prefixes" >> $RESULTS
    cat $RESULTS
images:
  - "us-docker.pkg.dev/my-project/demo/helloworld-image"
options:
  requested_verify_option: VERIFIED
  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "id": "build-step",
      "args": [
        "build",
        "-t",
        "us-docker.pkg.dev/my-project/demo/helloworld-image",
        "."
      ]
    },
    {
      "name": "ubuntu",
      "id": "check-source-fetch-urls",
      "results": [
        {
          "name": "allowlisted_prefixes",
          "attestationContent": "remote_fetch_allow_list",
          "attestationType": "https://cloudbuild.googleapis.com/attestations/build_content_restrictions"
        }
      ],
      "script": "#!/bin/bash\nprefixes=\"[\\\"github.com\\\", \\\"gitlab.com\\\"]\"\necho \"allowlisted_prefixes=$prefixes\" >> $RESULTS\ncat $RESULTS\n"
    }
  ],
  "images": [
    "us-docker.pkg.dev/my-project/demo/helloworld-image"
  ],
  "options": {
    "requested_verify_option": "VERIFIED",
    "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET"
  }
}

`timeout`

在建構步驟之外使用 timeout 欄位，設定執行建構作業的整體時間限制。如果超過這個時間，建構作業就會停止，且建構狀態會是 TIMEOUT。

如未設定 timeout，建構作業會使用預設的 timeout (60 分鐘)。timeout 的最大值為 24 小時。timeout 以秒為單位，使用時間長度格式，最多 9 個小數位數，結尾為 s (例如：3.5s)。

在下列程式碼片段中，timeout 設為 660 秒，以免建構作業因休眠而逾時：

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '600']
timeout: 660s

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "600"
        ]
    }
    ],
    "timeout": "660s"
}

`queueTtl`

使用 queueTtl 欄位指定建構作業可排入佇列的時間長度。如果建構作業在佇列中的時間超過 queueTtl 中設定的值，建構作業就會過期，且建構狀態會設為 EXPIRED。如未提供值，Cloud Build 會使用預設值 3600s (1 小時)。queueTtl從 createTime開始計時。queueTtl 必須以秒為單位指定，最多可有九個小數位數，並以「s」結尾，例如 3.5s。

在下列程式碼片段中，timeout 設為 20s，queueTtl 設為 10s。queueTtl 會在 createTime (要求建構的時間) 開始計時，timeout 則會在 startTime (建構開始的時間) 開始計時。因此，除非建構作業在 createTime + 10s 之前開始，否則 queueTtl 將在該時間到期。

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '5']
timeout: 20s
queueTtl: 10s

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "5"
        ]
    }
    ],
    "timeout": "20s",
    "queueTtl": "10s"
}

`logsBucket`

設定建構作業的 logsBucket 欄位，指定必須寫入建構記錄的 Cloud Storage bucket。如未設定這個欄位，Cloud Build 會使用 defaultLogsBucketBehavior 的值，將建構作業記錄儲存在 Cloud Storage 中由 Cloud Build 建立的 bucket。

下列程式碼片段會將 Cloud Build 設為將建構記錄儲存在 Cloud Storage 的自訂 bucket 中。

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
logsBucket: 'gs://mybucket'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ]
    }
    ],
    "logsBucket": "gs://mybucket"
}

`options`

使用 options 欄位，為建構作業指定下列選用引數：

enableStructuredLogging：建構記錄傳送至 Logging 時，可將指定的建構記錄欄位對應至 LogEntry 欄位。舉例來說，如果建構記錄包含 message，則產生的記錄項目中，訊息會顯示在 textPayload 或 jsonPayload.message。無法對應的建構記錄欄位會顯示在記錄項目 jsonPayload 中。詳情請參閱「將建構記錄欄位對應至記錄項目欄位」。

env：全域環境變數定義清單，適用於這項建構作業的所有建構步驟。如果變數同時定義於全域和建構步驟中，則會使用建構步驟的值。元素格式為 KEY=VALUE，環境變數 KEY 的值為 VALUE。

secretEnv：使用 Cloud Key Management Service 加密編譯金鑰加密的全域環境變數清單，可供這項建構作業中的所有建構步驟使用。這些值必須在建構作業的 Secret 中指定。

volumes：要為「所有」建構步驟全域掛接的磁碟區清單。在開始建構程序之前，每個磁碟區都會建立為空白磁碟區。建構作業完成後，磁碟區及其內容會遭到捨棄。全域磁碟區名稱和路徑不得與建構步驟中定義的磁碟區衝突。在只有一個步驟的建構作業中使用全域磁碟區是無效的，因為這代表建構要求設定不正確。

pubsubTopic：可選擇提供 Pub/Sub 主題名稱，用於接收建構狀態通知。如未提供名稱，Cloud Build 會使用預設主題名稱 cloud-builds。下列程式碼片段指定 Pub/Sub 主題名稱為 my-topic：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
    pubsubTopic: 'projects/my-project/topics/my-topic'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "pubsubTopic": "projects/my-project/topics/my-topic"
    }
}

sourceProvenanceHash：設定 sourceProvenanceHash 選項，指定來源來源的雜湊演算法。下列程式碼片段指定雜湊演算法為 SHA256：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
    sourceProvenanceHash: ['SHA256']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "sourceProvenanceHash": ["SHA256"]
    }
}

machineType：Cloud Build 提供四種高 CPU 虛擬機器類型來執行建構作業：兩種機型有 8 個 CPU，另外兩種機型有 32 個 CPU。Cloud Build 也提供兩種額外的虛擬機器類型，分別有 1 個和 2 個 CPU，可用來執行建構作業。預設機器類型為 e2-standard-2，搭載 2 個 CPU。要求高 CPU 虛擬機器可能會增加建構作業的啟動時間。新增 machineType 選項，要求 CPU 較高的虛擬機器：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 machineType: 'E2_HIGHCPU_8'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    },
    ],
    "options": {
        "machineType": "E2_HIGHCPU_8"
    }
}

如要進一步瞭解如何使用 machineType 選項，請參閱「加快建構速度」。

diskSizeGb：使用 diskSizeGb 選項，為建構作業要求自訂磁碟大小。可要求的大小上限為 4000 GB。

以下程式碼片段要求 200 GB 的磁碟大小：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 diskSizeGb: '200'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "diskSizeGb": '200'
    }
}

logStreamingOption：使用這個選項，指定是否要將建構記錄串流至 Cloud Storage。根據預設，Cloud Build 會在建構完成時收集建構記錄；這個選項可指定是否要在建構過程中即時串流建構記錄。以下程式碼片段指定系統會將建構記錄串流至 Cloud Storage：

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
options:
 logStreamingOption: STREAM_ON

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ]
    }
    ],
    "options": {
        "logStreamingOption": "STREAM_ON"
    }
}

logging：使用這個選項，指定要將建構記錄儲存在 Cloud Logging 還是 Cloud Storage：

GCS_ONLY：建構記錄會傳送至 Cloud Storage bucket。
CLOUD_LOGGING_ONLY：建構記錄會傳送至 Logging bucket。
LEGACY：建構作業記錄會傳送至這兩個位置的 bucket。如果未定義 logging，Cloud Build 會使用這個值。
NONE：不儲存建構作業記錄。

如要進一步瞭解建構記錄儲存空間的優點和注意事項，請參閱「建構記錄儲存空間選項」。

下列程式碼片段指定將建構記錄儲存在 Cloud Storage：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 logging: GCS_ONLY

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "logging": "GCS_ONLY"
    }
}

defaultLogsBucketBehavior：

如果 logging 設定為將建構記錄傳送至 Cloud Storage，請使用這個欄位。

如果 logging 的值為 GCS_ONLY、Legacy 或未定義，建構記錄會傳送至 Cloud Storage 中的 bucket。在這種情況下，Cloud Build 會評估 logsBucket 和 defaultLogsBucketBehavior 欄位，判斷哪個 Cloud Storage bucket 會接收建構記錄：

`logsBucket`	`defaultLogsBucketBehavior`	建構作業記錄檔的儲存位置
指定 bucket	忽略值	在 `logsBucket` 指定的值區中
沒有值	`REGIONAL_USER_OWNED_BUCKET`	在 Cloud Build 建立且由使用者擁有的 bucket 中
沒有值	`LEGACY_BUCKET`	在 Cloud Build 建立及 Google Cloud擁有的 bucket 中
沒有值	沒有值	Cloud Build 建立且使用者擁有的 bucket。如果無法建立這個 bucket，建構記錄會儲存在 Cloud Build 建立及擁有的 Google Cloudbucket。

詳情請參閱「建構記錄儲存空間選項」。

下列建構設定會將 defaultLogsBucketBehavior 欄位設為 REGIONAL_USER_OWNED_BUCKET 值：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
options:
  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "-t",
        "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
        "."
      ]
    }
    ],
    "options": {
      "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET"
    }
}

dynamicSubstitutions：使用這個選項，明確啟用或停用替代變數中的 bash 參數擴展。如果建構作業是由觸發條件叫用，dynamicSubstitutions 欄位一律會設為 true，且不需在建構設定檔中指定。如果手動叫用建構作業，則必須將 dynamicSubstitutions 欄位設為 true，以便在執行建構作業時解譯 bash 參數擴充。

automapSubstitutions：自動將所有替代項目對應至環境變數，這些變數將在整個建構作業中可用。如需範例，請參閱「替換變數值」。

substitutionOption：您將設定這個選項和下方的 substitutions 欄位，指定替代檢查發生錯誤時的行為。

pool：將這個欄位的值設為要執行建構作業的私人集區資源名稱。如需在私人集區中執行建構作業的操作說明，請參閱「在私人集區中執行建構作業」。

requestedVerifyOption：將 requestedVerifyOption 的值設為 VERIFIED，即可啟用並驗證建構作業的認證和來源中繼資料。設定完成後，只有在產生認證和來源時，建構作業才會標示為 SUCCESS。

workerRelease：選擇發布管道或特定版本。

下列建構設定會將 workerRelease 欄位設為一般版：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
options:
  workerRelease: regular

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "-t",
        "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
        "."
      ]
    }
    ],
    "options": {
      "workerRelease": "regular"
    }
}

以下範例則將 workerRelease 欄位設為特定版本：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
options:
  workerRelease: 2026.09

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "-t",
        "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
        "."
      ]
    }
    ],
    "options": {
      "workerRelease": "2026.09"
    }
}

`substitutions`

在建構設定檔中使用替代項目，即可在建構時替換特定變數。如果變數的值在建構時才會得知，或您想搭配不同的變數值重複使用現有的建構要求，替代變數就非常實用。根據預設，如果缺少替代變數或替代項目，建構作業會傳回錯誤。不過，您可以使用 ALLOW_LOOSE 選項略過這項檢查。

以下程式碼片段使用 substitutions 輸出「hello world」。ALLOW_LOOSE substitution 選項已設定，表示如果有遺失的 substitution 變數或遺失的 substitution，建構不會傳回錯誤。

YAML

steps:
- name: 'ubuntu'
  args: ['echo', 'hello ${_SUB_VALUE}']
substitutions:
    _SUB_VALUE: world
options:
    substitution_option: 'ALLOW_LOOSE'

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello ${_SUB_VALUE}"
        ]
    }
    ],
    "substitutions": {
        "_SUB_VALUE": "world"
},
    "options": {
        "substitution_option": "ALLOW_LOOSE"
    }
}

如需使用 substitutions 的其他操作說明，請參閱「替換變數值」。

`tags`

使用 tags 欄位將建構作業分組，並篩選建構作業。下列設定會設定兩個名為 mytag1 和 mytag2 的標記：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  ...
- name: 'ubuntu'
  ...
tags: ['mytag1', 'mytag2']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker"
    },
    {
        "name": "ubuntu"
    }
    ],
    "tags": [
        "mytag1",
        "mytag2"
    ]
}

`availableSecrets`

在建構要求中，使用這個欄位參照 Secret Manager 或 Cloud KMS 中的一或多個 Secret。Cloud Build 可使用這些 Secret 在建構程序中執行動作，例如登入帳戶。

Secret Manager

如要在建構設定檔中使用 Secret Manager 密鑰，請在建構設定檔的 availableSecrets 欄位中新增 secretManager 欄位。secretManager 欄位包含一或多組 versionName 和 env 欄位：

versionName：Secret Manager 中的 Secret 路徑。
env：本機名稱 (環境變數)，建構步驟可使用此名稱參照 Secret。

建構步驟中的 secretEnv 欄位會指定該步驟可使用的環境變數。

下列設定說明如何使用儲存在 Secret Manager 中的 Docker 使用者名稱和密碼登入 Docker：

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/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION
        env: 'PASSWORD'
      - versionName: projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION
        env: 'USERNAME'

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/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION",
      "env": "PASSWORD"
  }, {
    "versionName": "projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION",
    "env": "USERNAME"
      }]
  }
}

詳情請參閱「使用 Secret」。

Cloud KMS

如要在建構設定檔中使用 Cloud KMS 金鑰，請在建構設定檔的 availableSecrets 欄位中新增 inline 欄位。inline 欄位包含一或多組 kmsKeyName 和 envMap：

kmsKeyName：Cloud KMS 金鑰的路徑。
envMap：本機名稱 (環境對應)，建構步驟可使用這個名稱參照 Secret。

建構步驟中的 secretEnv 欄位會指定該步驟可使用的環境變數。

下列設定說明如何使用儲存在 Cloud KMS 中的 Docker 使用者名稱和密碼登入 Docker。

YAML

     steps:
     - name: 'gcr.io/cloud-builders/docker'
       entrypoint: 'bash'
       args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
       secretEnv: ['USERNAME', 'PASSWORD']
     - name: 'gcr.io/cloud-builders/docker'
       entrypoint: 'bash'
       args: ['-c', 'docker pull $$USERNAME/IMAGE:TAG']
       secretEnv: ['USERNAME']
     availableSecrets:
       inline:
       - kmsKeyName: projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAME
         envMap:
           USERNAME: 'ENCRYPTED_USERNAME'
       - kmsKeyName: projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAME
         envMap:
           PASSWORD: 'ENCRYPTED_PASSWORD'

JSON

{
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker login --username=$$USERNAME --password=$$PASSWORD"
    ],
    "secretEnv": [
      "USERNAME",
      "PASSWORD"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker pull $$USERNAME/REPOSITORY:TAG"
      ],
      "secretEnv": [
      "USERNAME"
    ]
  }
  ],
  "availableSecrets": {
    "inline": [{
      "kmsKeyName": "projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAME",
      "envMap": {
        "USERNAME": "ENCRYPTED_USERNAME"
        }
    },
    {
    "kmsKeyName": "projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAME",
    "envMap": {
        "PASSWORD": "ENCRYPTED_PASSWORD"
        }
    }]
  }
}

`secrets`

Secret 會將一組包含加密值的密鑰環境變數，與用於解密值的 Cloud KMS 金鑰配對。

`serviceAccount`

使用這個欄位指定要在建構時使用的 IAM 服務帳戶。詳情請參閱「設定使用者指定的服務帳戶」。

您無法在這個欄位中指定舊版 Cloud Build 服務帳戶。

`images`

建構設定檔中的 images 欄位會指定一或多個 Linux Docker 映像檔，由 Cloud Build 推送至 Artifact Registry。您可能會有執行工作但不產生任何 Linux Docker 映像檔的建構作業，但如果您建構映像檔卻未推送至登錄檔，則映像檔會在建構完成時遭到捨棄。如果建構期間未產生指定映像檔，建構作業就會失敗。如要進一步瞭解如何儲存映像檔，請參閱「在 Artifact Registry 中儲存構件」。

下列建構設定會設定 images 欄位，用於儲存建構的映像檔：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
images: ['gcr.io/myproject/myimage']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "images": [
        "gcr.io/myproject/myimage"
    ]
}

`artifacts`

artifacts 欄位會指定一或多個構件，在所有建構步驟成功完成後，儲存至 Cloud Storage 或 Artifact Registry。

`objects`

在 artifacts 欄位中，object 欄位會指定要儲存在 Cloud Storage 中的一或多個構件。詳情請參閱「將建構構件儲存在 Cloud Storage」。

下列建構設定會設定 artifacts 欄位，將建構的 Go 套件儲存在 gs://mybucket/ 中：

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['build', 'my-package']
artifacts:
  objects:
    location: 'gs://mybucket/'
    paths: ['my-package']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "build",
            "my-package"
        ]
    }
    ],
    "artifacts": {
      "objects": {
        "location": "gs://mybucket/",
        "paths": [
            "my-package"
        ]
      }
    }
}

`goModules`

goModules 欄位可讓您將非容器 Go 模組上傳至 Artifact Registry 中的 Go 存放區。詳情請參閱「建構及測試 Go 應用程式」。

repository_location 欄位會指定要儲存套件的 Artifact Registry 存放區。module_path 欄位會指定本機目錄，其中包含要上傳的 Go 模組。這個目錄必須包含 go.mod 檔案。

建議您為 module_path 的值使用絕對路徑。您可以使用 . 參照目前使用的目錄，但不得省略或留空這個欄位。如需使用 module_path 的詳細操作說明，請參閱「建構及測試 Go 應用程式」。

下列建構設定會設定 goModules 欄位，將 example.com/myapp 中的模組上傳至 Artifact Registry 存放區 quickstart-go-repo：

YAML

artifacts:
  goModules:
    - repositoryName: 'quickstart-go-repo'
      repositoryLocation: 'us-central1'
      repositoryProjectId: 'argo-local-myname'
      sourcePath: '/workspace/myapp'
      modulePath: 'example.com/myapp'
      moduleVersion: 'v1.0.0'

JSON

{
  "artifacts": {
    "goModules": [
     {
      "repositoryName": "quickstart-go-repo",
      "repositoryLocation": "us-central1",
      "repositoryProjectId": "argo-local-myname",
      "sourcePath": "/workspace/myapp",
      "modulePath": "example.com/myapp",
      "moduleVersion": "v1.0.0"
     }
    ]
  }
}

`mavenArtifacts`

mavenArtifacts 欄位可讓您將非容器 Java 構件上傳至 Artifact Registry 中的 Maven 存放區。詳情請參閱「建構及測試 Java 應用程式」。

範例：將資料夾中的所有 Maven 檔案上傳至 Artifact Registry 存放區

下列建構設定會設定 mavenArtifacts 欄位，將 /workspace/target/com/mycompany/app/my-app-1/1.0.0/ 資料夾中的所有檔案上傳至 Artifact Registry 存放區 https://us-central1-maven.pkg.dev/my-project-id/my-java-repo：

YAML

artifacts:
  mavenArtifacts:
    - repository: 'https://us-central1-maven.pkg.dev/my-project-id/my-java-repo'
      deployFolder: '/workspace/target'
      artifactId: 'my-app-1'
      groupId: 'com.mycompany.app'
      version: '1.0.0'

JSON

{
  "artifacts": {
    "mavenArtifacts": [
      {
        "repository": "https://us-central1-maven.pkg.dev/my-project-id/my-java-repo",
        "deployFolder": "/workspace/target",
        "artifactId": "my-app-1",
        "groupId": "com.mycompany.app",
        "version": "1.0.0"
      }
    ]
  }
}

如要將 Maven 檔案部署至 /workspace/target/com/mycompany/app/my-app-1/1.0.0/，請在 Maven 部署指令中加入 -DaltDeploymentRepository=local::default::file:./workspace/target 選項。

範例：將封裝的 Maven 檔案上傳至 Artifact Registry 存放區

下列建構設定會設定 mavenArtifacts 欄位，將封裝檔案 my-app-1.0-SNAPSHOT.jar 上傳至 Artifact Registry 存放區 https://us-central1-maven.pkg.dev/my-project-id/my-java-repo：

YAML

artifacts:
  mavenArtifacts:
    - repository: 'https://us-central1-maven.pkg.dev/my-project-id/my-java-repo'
      path: '/workspace/my-app/target/my-app-1.0-SNAPSHOT.jar'
      artifactId: 'my-app-1'
      groupId: 'com.mycompany.app'
      version: '1.0.0'

JSON

{
  "artifacts": {
    "mavenArtifacts": [
      {
        "repository": "https://us-central1-maven.pkg.dev/my-project-id/my-java-repo",
        "path": "/workspace/my-app/target/my-app-1.0-SNAPSHOT.jar",
        "artifactId": "my-app-1",
        "groupId": "com.mycompany.app",
        "version": "1.0.0"
      }
    ]
  }
}

`pythonPackages`

pythonPackages 欄位可讓您將 Python 套件上傳至 Artifact Registry。詳情請參閱「建構及測試 Python 應用程式」。

下列建構設定會設定 pythonPackages 欄位，將 Python 套件 dist/my-pkg.whl 上傳至 Artifact Registry 存放區 https://us-east1-python.pkg.dev/my-project/my-repo：

YAML

artifacts:
  pythonPackages:
   - repository: 'https://us-east1-python.pkg.dev/my-project/my-repo'
     paths: ['dist/my-pkg.whl']

JSON

{
  "artifacts": {
    "pythonPackages": [
      {
        "repository": "https://us-east1-python.pkg.dev/my-project/my-repo",
        "paths": ["dist/my-pkg.whl"]
      }
    ]
  }
}

`npmPackages`

使用 npmPackages 欄位，設定 Cloud Build 將建構的 npm 套件上傳至 Artifact Registry 中支援的存放區。您必須提供 repository 和 packagePath 的值。

repository 欄位會指定要儲存套件的 Artifact Registry 存放區。packagePath 欄位會指定本機目錄，其中包含要上傳的 npm 套件。這個目錄必須包含 package.json 檔案。

建議您為 packagePath 的值使用絕對路徑。您可以使用 . 參照目前使用的目錄，但不得省略或留空這個欄位。如要進一步瞭解如何使用 npmPackages，請參閱「建構及測試 Node.js 應用程式」。

下列建構設定會設定 npmPackages 欄位，將 /workspace/my-pkg 目錄中的 npm 套件上傳至 Artifact Registry 存放區 https://us-east1-npm.pkg.dev/my-project/my-repo。

YAML

artifacts:
  npmPackages:
   - repository: 'https://us-east1-npm.pkg.dev/my-project/my-repo'
     packagePath: '/workspace/my-pkg'

JSON

{
  "artifacts": {
    "npmPackages": [
      {
        "repository": "https://us-east1-npm.pkg.dev/my-project/my-repo",
        "packagePath": "/workspace/my-pkg"
      }
    ]
  }
}

`oci`

使用 oci 欄位，設定 Cloud Build 將 OCI 映像檔上傳至 Artifact Registry 中支援的存放區。您必須提供 file 和 registryPath 的值。

registryPath 欄位會指定要儲存映像檔的 Artifact Registry 存放區。file 欄位會指定本機目錄，其中包含要上傳的 OCI 映像檔。這個目錄必須包含 OCI 映像檔。

建議您為 file 的值使用絕對路徑。您可以使用 . 參照目前使用的目錄，但不得省略這個欄位或留空。

下列建構設定會設定 oci 欄位，將 /.pack/layout-repo/my-app 目錄中的 OCI 映像檔上傳至 Artifact Registry 存放區 https://us-east1-docker.pkg.dev/my-project/my-repo。

YAML

artifacts:
  oci:
  - file: '/.pack/layout-repo/my-app'
    registryPath: 'https://us-east1-docker.pkg.dev/my-project/my-repo'
    tags: ["primary_image"]

JSON

{
  "artifacts": {
    "oci": [
      {
        "file": "/.pack/layout-repo/my-app",
        "registryPath": "https://us-east1-docker.pkg.dev/my-project/my-repo",
        "tags": ["primary_image"]
      }
    ]
  }
}

`genericArtifacts`

使用 genericArtifacts 欄位，將未指定類型的檔案上傳為 Artifact Registry 一般存放區中的新套件。如要上傳文字檔或二進位檔等一般檔案，或上傳不屬於 Artifact Registry 存放區類型的套件，這項設定就非常實用。

folder 欄位會指定要上傳至一般存放區的檔案所在資料夾。registryPath 欄位是 Artifact Registry 一般存放區的位址，用於接收資料夾中的檔案。

下列建構設定會設定 genericArtifacts 欄位，將 /workspace/binaryOut 資料夾上傳至 Artifact Registry 一般存放區 projects/my-project/locations/us-east1/repositories/my-repo/packages/my-pkg/versions/my-version。

YAML

artifacts:
  genericArtifacts:
  - folder: '/workspace/binaryOut'
    registryPath: 'projects/my-project/locations/us-east1/repositories/my-repo/packages/my-pkg/versions/my-version'

JSON

{
  "artifacts": {
    "genericArtifacts": [
      {
        "folder": "/workspace/binaryOut",
        "registryPath": "projects/my-project/locations/us-east1/repositories/my-repo/packages/my-pkg/versions/my-version"
      }
    ]
  }
}

您可以將一般構件設為建構依附元件，讓 Cloud Build 在建構作業開始前下載依附元件。詳情請參閱「將一般構件指定為依附元件」。

使用 Dockerfile

如果您使用 gcloud CLI 或自動建構觸發條件，在 Cloud Build 中執行 Docker 建構作業，則可以使用 Dockerfile，而不必使用個別的建構設定檔。如要進一步調整 Docker 建構作業，除了 Dockerfile 之外，您也可以提供建構設定檔。如要瞭解如何使用 Dockerfile 建構 Docker 映像檔，請參閱「快速入門導覽課程：建構」。

Cloud Build 網路

Cloud Build 執行每個建構步驟時，會將步驟的容器附加至名為 cloudbuild 的本機 Docker 網路。cloudbuild 網路會託管應用程式預設憑證 (ADC)， Google Cloud 服務可使用這些憑證自動尋找您的憑證。如果您執行巢狀 Docker 容器，並想將 ADC 公開至基礎容器，或在 docker 步驟中使用 gcloud，請在 Docker build 步驟中使用 --network 旗標：

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '--network=cloudbuild', '.']

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "--network=cloudbuild",
        "."
      ]
   }
  ]
}

後續步驟

瞭解如何建立基本的建構設定檔來設定 Cloud Build 的建構。
如需如何在 Cloud Build 中執行建構的操作說明，請參閱以手動方式啟動建構一文。

建構設定檔結構定義 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

建構設定檔的結構

YAML

JSON

建構步驟

YAML

JSON

name

YAML

JSON

args

YAML

JSON

env

YAML

JSON

allowFailure

YAML

JSON

allowExitCodes

YAML

JSON

dir

YAML

JSON

ID

waitFor

entrypoint

YAML

JSON

secretEnv

volumes

YAML

JSON

timeout

YAML

JSON

script

automapSubstitutions

結果

YAML

JSON

timeout

YAML

JSON

queueTtl

YAML

JSON

logsBucket

YAML

JSON

options

YAML

JSON

YAML

JSON

YAML

JSON

YAML

JSON

YAML

JSON

YAML

JSON

YAML

JSON

YAML

JSON

YAML

JSON

substitutions

YAML

JSON

tags

YAML

JSON

availableSecrets

YAML

JSON

YAML

建構設定檔結構定義

`name`

`args`

`env`

`allowFailure`

`allowExitCodes`

`dir`

`waitFor`

`entrypoint`

`secretEnv`

`volumes`

`timeout`

`timeout`

`queueTtl`

`logsBucket`

`options`

`substitutions`

`tags`

`availableSecrets`

`secrets`

`serviceAccount`

`images`

`artifacts`

`objects`

`goModules`

`mavenArtifacts`

`pythonPackages`

`npmPackages`

`oci`

`genericArtifacts`