本頁面由 Cloud Translation API 翻譯而成。

建構設定檔結構定義

建構設定檔中包含讓 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
- 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)
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"
    },
    {
        "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)"
        "requestedVerifyOption": "enum(RequestedVerifyOption)"
    },
    "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 欄位會先設定 Compute Engine 區域與 GKE 叢集，然後再執行 kubectl：

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

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

`timeout`

在建構步驟中使用 timeout 欄位可設定執行步驟的時間限制。如果您並未設定這個欄位，步驟會沒有時間限制，可執行到其完成或建構自身逾時為止。建構步驟中的 timeout 欄位不得超過建構作業指定的 timeout 值。timeout 必須以秒為單位，最多可有 9 個小數位數，結尾為「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 欄位，指定要在步驟中執行的 Shell 指令碼。如果您在建構步驟中指定 script，則無法在同一步驟中指定 args 或 entrypoint。如需使用 script 欄位的操作說明，請參閱「執行 bash 指令稿」一文。

automapSubstitutions

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

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`

磁碟區是一種 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"
        ]
     }
    ]
  }

`allowFailure`

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

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

allowExitCodes 的優先順序高於此欄位。

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

YAML

steps:
- name: 'ubuntu'
  args: ['-c', 'exit 1']
  allowFailure: true
steps:
- 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]
steps:
- name: 'ubuntu'
  args: ['echo', 'Hello World']

JSON

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

`timeout`

針對建構使用 timeout 欄位可指定必須允許建構執行的時間長度 (精確到秒)。如果過了這個時間，建構工作將停止，且建構狀態將會是 TIMEOUT。如果未設定 timeout，系統會將預設的 timeout 60 分鐘套用至建構。可套用至 timeout 的最大值為 24 小時。timeout 必須以秒為單位指定，且不得超過九個小數位數，結尾必須是「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 值區。如果您並未設定這個欄位，Cloud Build 將使用預設值區儲存建構記錄。

以下程式碼片段會設定儲存建構記錄的記錄值區：

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 個 CPU 和 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 中儲存記錄。如果您並未設定這個選項，Cloud Build 會將記錄儲存在 Cloud Logging 與 Cloud Storage 中。您可以將 logging 選項設為 GCS_ONLY，以僅在 Cloud Storage 中儲存記錄。以下程式碼片段指定系統會將記錄儲存在 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：defaultLogsBucketBehavior 選項可讓您設定 Cloud Build，在專案所在地區 (與建構作業相同) 內建立預設記錄值區。詳情請參閱「在使用者擁有的區域化值區中儲存建構記錄」。

以下建構設定會將 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。

`substitutions`

在建構設定檔中使用 substitutions 可在建構時間替換特定變數。對於值在建構之前仍未知的變數，或者以不同變數值重複使用現有建構要求而言，substitutions 很實用。根據預設，如果有遺失的 substitution 變數或遺失的 substitution，建構會傳回錯誤，不過，您可以使用 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`

使用這個欄位，即可在 Cloud Build 中使用 Secret Manager 中的密鑰。詳情請參閱「使用密鑰」。

`secrets`

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

`serviceAccount`

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

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

`images`

建構設定檔中的 images 欄位指定要由 Cloud Build 推送至 Artifact Registry 的一或多個 Linux Docker 映像檔。您的建構可能會執行工作而不產生任何 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 中的一或多個非容器成果。如要進一步瞭解如何儲存非容器成果，請參閱「將建構成果儲存在 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'
    repositoryProject_id: 'argo-local-myname'
    sourcePath: '/workspace/myapp'
    modulePath: 'example.com/myapp'
    moduleVersion: 'v1.0.0'

JSON

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

`mavenArtifacts`

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

以下建構設定會設定 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"
      }
    ]
  }
}

使用 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

dir

YAML

JSON

timeout

YAML

JSON

script

automapSubstitutions

ID

waitFor

entrypoint

YAML

JSON

secretEnv

volumes

YAML

JSON

allowFailure

YAML

JSON

allowExitCodes

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

substitutions

YAML

JSON

tags

YAML

JSON

availableSecrets

secrets

serviceAccount

images

YAML

JSON

artifacts

YAML

JSON

goModules

YAML

建構設定檔結構定義

`name`

`args`

`env`

`dir`

`timeout`

`waitFor`

`entrypoint`

`secretEnv`

`volumes`

`allowFailure`

`allowExitCodes`

`timeout`

`queueTtl`

`logsBucket`

`options`

`substitutions`

`tags`

`availableSecrets`

`secrets`

`serviceAccount`

`images`

`artifacts`

`goModules`

`mavenArtifacts`

`pythonPackages`

`npmPackages`