此页面由 Cloud Translation API 翻译。

构建配置文件架构

构建配置文件包含 Cloud Build 根据您的规范执行任务的说明。例如，您的构建配置文件可以包含构建、打包和推送 Docker 映像的说明。

本页面介绍了 Cloud Build 构建配置文件的架构。如需了解如何创建和使用构建配置文件，请参阅创建基本的构建配置文件。

构建配置文件的结构

构建配置文件使用 Cloud Build API 的 Build 资源进行建模。

您可以使用 YAML 或 JSON 语法编写构建配置文件。如果您使用第三方 http 工具（如 curl）提交构建请求，请使用 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)
 requestedVerifyOption: enum(RequestedVerifyOption)
substitutions: map (key: string, value: string)
tags: [string, string, ...]
serviceAccount: string
secrets: object(Secret)
availableSecrets: object(Secrets)
artifacts: object(Artifacts)
  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)",
      "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 字段来指定 Cloud Builder，这是一种运行常见工具的容器映像。您可以在构建步骤中使用构建器来执行任务。

以下代码段展示了调用 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"
        ]
    }
    ]
}

`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 必须以秒为单位指定，最多包含九个小数位，并以“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 字段指定要执行的 Shell 脚本步骤。如果您在构建步骤中指定 script，则不能指定 args 或 entrypoint。如需了解如何使用 script 字段，请参阅运行 bash 脚本。

automapSubstitutions

如果设置为 true，系统会自动映射所有替换项，并在单个步骤中将其作为环境变量提供。如果设置为 false，则忽略相应步骤的替换项。如需查看示例，请参阅替换变量值。

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，并且构建步骤失败，那么只要该构建中的所有其他构建步骤都成功完成，构建就会成功。

如果 build 中的所有 build 步骤都将 allowFailure 设置为 true，并且所有 build 步骤都失败，则 build 的状态仍为 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 中），则整个构建将会失败。

与 build 相关的退出代码取决于您的软件。例如，"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（即构建的启动时间）开始计时。因此，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可选参数：

env：将存在于此构建的所有构建步骤中的全局环境变量定义列表。如果同时在全局范围内和构建步骤中定义了变量，则该变量将使用构建步骤值。元素的格式为 KEY=VALUE，表示环境变量 KEY 的值为 VALUE。

secretEnv：使用 Cloud Key Management Service 加密密钥加密的全局环境变量列表，这些变量可用于此构建中的所有构建步骤。您必须在构建的 Secret 中指定这些值。

volumes：要在全局范围内为所有构建步骤装载的卷列表。在开始构建过程之前，每个卷都是作为空卷创建的。构建完成后，系统会舍弃卷及其内容。全局卷名称和路径不能与构建步骤定义的卷冲突。在只有一个步骤的构建中使用全局卷是无效的，因为它意味着构建请求的配置不正确。

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 会将日志存储在 Stackdriver 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 字段始终设置为，无需在构建配置文件中指定。如果是手动调用您的构建，则必须将 dynamicSubstitutions 字段设置为 true，以便在运行构建时解读 bash 参数扩展。

automapSubstitutions：自动将所有替换项映射到将在整个 build 中可用的环境变量。如需查看示例，请参阅替换变量值。

substitutionOption：您将设置此选项和下面的 substitutions 字段，以指定当替代变量检查出现错误时采取的行为。

pool：将该字段的值设置为要运行构建的专用池的资源名称。如需了解如何在专用池上运行构建，请参阅在专用池中运行构建。

requestedVerifyOption：将 requestedVerifyOption 的值设置为 VERIFIED，以启用和验证为 build 生成认证和来源元数据。设置完成后，只有在生成了证明和来源信息时，您的 build 才会被标记为 SUCCESS。

`substitutions`

在构建配置文件中使用 substitutions 以在构建时替换特定变量。对于那些直到构建时才知道值的变量，或者使用不同的变量值重用现有构建请求，替代变量很有用。默认情况下，如果缺少替代变量或缺少替换，则构建将返回错误。但您可以使用 ALLOW_LOOSE 选项跳过此检查。

以下代码段使用替代变量来打印“hello world”。ALLOW_LOOSE 替换选项已设置，这意味着如果缺少替代变量或缺少替换，则构建不会返回错误。

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 中的 Secret 与 Cloud Build 结合使用。如需了解详情，请参阅使用 Secret。

`secrets`

Secret 将包含加密值的一组 secret 环境变量与用于解密该值的 Cloud KMS 密钥进行配对。

`serviceAccount`

使用此字段指定要在构建时使用的 IAM 服务账号。如需了解详情，请参阅配置用户指定的服务账号。

`images`

构建配置文件中的 images 字段指定由 Cloud Build 推送到 Artifact Registry 或 Container 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 中的一个或多个非容器工件。如需详细了解存储非容器工件，请参阅将构建工件存储在 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"
        ]
      }
    }
}

`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 字段以上传 npm 将 /workspace/my-pkg 目录中的软件包复制到 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

如果您在 Cloud Build 中使用 gcloud CLI 或构建触发器，那么您可以使用 Dockerfile，而无需单独的构建配置文件。如果您希望对 Docker 构建进行更多调整，那么除了 Dockerfile 之外，您还可以提供构建配置文件。如需了解如何使用 Dockerfile 来构建 Docker 映像，请参阅快速入门：构建。

Cloud Build 网络

在 Cloud Build 运行每个构建步骤时，它会将相应步骤的容器连接到一个名为 cloudbuild 的本地 Docker 网络。cloudbuild 网络托管着应用默认凭据 (ADC)，Google Cloud 服务可使用 ADC 来自动查找您的凭据。如果您运行的是嵌套的 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 中运行构建。