本頁面由 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 以秒為單位指定 (使用Duration 格式)，最多可有 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 欄位，指定要在步驟中執行的殼層指令碼。如果在建構步驟中指定 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 會允許這個建構步驟失敗，但不會導致整個建構作業失敗。

如果所有建構步驟都失敗，但每個步驟都以您在 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，建構作業會使用 60 分鐘的預設 timeout。timeout 的最大值為 24 小時。timeout 以秒為單位指定，使用 Duration 格式，最多可有 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 中設定的值，建構作業就會過期，且 build status 會設為 EXPIRED。如未提供值，Cloud Build 會使用預設值 3600s (1 小時)。queueTtl從 createTime開始計算。queueTtl 必須以秒為單位指定，且不得超過九個小數位數，結尾必須是「s」，例如 3.5s。

在下列程式碼片段中，timeout 會設為 20s，而 queueTtl 會設為 10s。queueTtl 會在 createTime 開始計時，也就是建構要求送達的時間；timeout 則會在 startTime 開始計時，也就是建構開始的時間。因此，除非建構作業在 createTime + 10s 前啟動，否則 queueTtl 會在 createTime + 10s 到期。

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，在專案中建立預設記錄檔 bucket，並與建構作業位於相同區域。詳情請參閱「將建構記錄儲存在使用者擁有的特定區域 bucket」。

以下建構設定會將 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 可在建構時間替換特定變數。對於值在建構之前仍未知的變數，或者以不同變數值重複使用現有建構要求而言，替代變數很實用。根據預設，如果有遺失的 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'
      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 應用程式」。

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