设置自动构建
注意
自动构建需要 Docker Pro、Team 或 Business 订阅.
此页面包含有关以下方面的信息：
配置自动构建
您可以配置 Docker Hub 中的存储库，以便它们在您将新代码推送到源代码提供者时自动构建镜像。如果您已配置 自动测试，则只有在测试成功后才会推送新镜像。
从 **存储库** 部分中，选择一个存储库以查看其详细信息。
选择 **构建** 选项卡。
选择 GitHub 或 Bitbucket 以连接镜像源代码所在的存储位置。
注意
您可能会被重定向到设置页面以 链接 代码存储库服务。否则，如果您正在编辑现有自动构建的构建设置，请单击 **配置自动构建**。
选择要从中构建 Docker 镜像的 **源存储库**。
注意
您可能需要从源代码提供者中指定一个组织或用户。选择用户后，源代码存储库将显示在 **选择存储库** 下拉列表中。
可选：启用 自动测试.
查看默认的 **构建规则**。
构建规则控制 Docker Hub 从源代码存储库内容中构建成镜像的方式，以及如何将生成的镜像标记在 Docker 存储库中。
默认情况下会为您设置一个构建规则，您可以编辑或删除它。此默认规则会从源代码存储库中的名为 `master` 或 `main` 的 `分支` 中进行构建，并创建一个标记为 `latest` 的 Docker 镜像。有关更多信息，请参阅 设置构建规则
可选：选择 **加号** 图标以添加和 配置更多构建规则.
对于每个分支或标签，启用或禁用 **自动构建** 切换。
只有启用了自动构建的分支或标签才会被构建、测试，并将生成的镜像推送到存储库。禁用了自动构建的分支会为测试目的进行构建（如果在存储库级别启用了测试），但不会将构建的 Docker 镜像推送到存储库。
对于每个分支或标签，启用或禁用 **构建缓存** 切换。
构建缓存 可以节省时间，尤其是在您经常构建大型镜像或有许多依赖项的情况下。保持构建缓存禁用以确保在构建时解析所有依赖项，或者如果您有一个大型层，该层在本地构建更快。
选择 **保存** 以保存设置，或选择 **保存并构建** 以保存并运行初始测试。
注意
将在您的源代码存储库中自动添加一个 webhook，以便在每次推送时通知 Docker Hub。只有对列为一个或多个标签来源的分支的推送才会触发构建。
设置构建规则
默认情况下，当您设置自动构建时，会为您创建一个基本的构建规则。此默认规则会监视源代码存储库中 `master` 或 `main` 分支的更改，并将 `master` 或 `main` 分支构建成一个标记为 `latest` 的 Docker 镜像。
在 **构建规则** 部分中，输入一个或多个要构建的来源。
对于每个来源
选择 **来源类型** 以构建标签或分支。这会告诉构建系统在源代码存储库中查找什么。
输入要构建的 **来源** 分支或标签的名称。
第一次配置自动构建时，会为您设置一个默认构建规则。此默认规则会从源代码存储库中的名为 `master` 的 `分支` 中进行构建，并创建一个标记为 `latest` 的 Docker 镜像。
您还可以使用正则表达式来选择要构建的来源分支或标签。要了解更多信息，请参阅 正则表达式.
输入要应用于从该来源构建的 Docker 镜像的标签。
如果您配置了正则表达式来选择来源，则可以引用捕获组并将结果用作标签的一部分。要了解更多信息，请参阅 正则表达式.
将 **Dockerfile 位置** 指定为相对于源代码存储库根目录的路径。如果 Dockerfile 位于存储库根目录，请将此路径设置为 ` /` 。
注意
当 Docker Hub 从源代码存储库中提取分支时，它会执行浅克隆 - 仅克隆指定分支的顶端。有关更多信息，请参阅 自动构建和自动测试的高级选项。
构建的环境变量
在配置自动构建时，可以设置用于构建过程中的环境变量的值。通过选择 **构建环境变量** 部分旁边的 **加号** 图标，然后输入变量名称和值来添加构建环境变量。
当您从 Docker Hub UI 设置变量值时，可以通过在 `hooks` 文件中设置的命令使用它们。但是，它们的存储方式是为了确保只有对 Docker Hub 存储库具有 `admin` 访问权限的用户才能看到它们的值。这意味着您可以使用它们来存储访问令牌或其他应保密的信息。
注意
在构建配置屏幕上设置的变量仅在构建过程中使用，不应与您的服务使用的环境值混淆，例如创建服务链接。
高级自动构建选项
至少需要一个由源分支或标签和目标 Docker 标签组成的构建规则才能设置自动构建。您还可以
- 更改构建查找 Dockerfile 的位置
- 设置构建应使用的文件路径（构建上下文）
- 设置要构建的多个静态标签或分支
- 使用正则表达式（regexes）动态选择要构建的源代码并创建动态标签
所有这些选项都可以在每个存储库的 **构建配置** 屏幕中找到。从左侧导航中选择 **存储库**，然后选择要编辑的存储库的名称。选择 **构建** 选项卡，然后选择 **配置自动构建**。
标记和分支构建
您可以配置自动构建，以便对特定分支或标签的推送触发构建。
在 **构建规则** 部分中，选择 **加号** 图标以添加更多要构建的来源。
选择 **来源类型** 以构建标签或分支。
注意
这会告诉构建系统在代码存储库中查找哪种类型的来源。
输入要构建的 **来源** 分支或标签的名称。
注意
您可以输入名称，或使用正则表达式来匹配要构建的来源分支或标签名称。要了解更多信息，请参阅 正则表达式.
输入要应用于从该来源构建的 Docker 镜像的标签。
注意
如果您配置了正则表达式来选择来源，则可以引用捕获组并将结果用作标签的一部分。要了解更多信息，请参阅 正则表达式.
对您设置的每个新的构建规则重复步骤 2 到 4。
设置构建上下文和 Dockerfile 位置
根据您在源代码存储库中组织文件的方式，构建镜像所需的文件可能不在存储库根目录中。如果是这种情况，您可以指定构建查找文件的路径。
构建上下文是构建所需文件相对于存储库根目录的路径。在 **构建上下文** 字段中输入这些文件的路径。输入 ` /` 以将构建上下文设置为源代码存储库的根目录。
注意
如果您从 **构建上下文** 字段中删除默认路径 ` /` 并将其留空，则构建系统会将 Dockerfile 的路径用作构建上下文。但是，为了避免混淆，建议您指定完整路径。
您可以将 **Dockerfile 位置** 指定为相对于构建上下文的路径。如果 Dockerfile 位于构建上下文路径的根目录中，请将 Dockerfile 路径设置为 ` /` 。如果构建上下文字段为空，请从源存储库的根目录中设置 Dockerfile 的路径。
正则表达式和自动构建
您可以指定正则表达式（regex），以便仅构建匹配的分支或标签。您还可以使用正则表达式的结果来创建应用于构建映像的 Docker 标签。
您可以使用最多九个正则表达式捕获组（或括号内的表达式）来选择要构建的源，并在 **Docker 标签** 字段中使用 {\1} 到 {\9} 来引用它们。
使用 BuildKit 构建镜像
自动构建默认使用 BuildKit 构建系统。如果您想使用传统的 Docker 构建系统，请添加 环境变量 DOCKER_BUILDKIT=0。有关 BuildKit 的更多信息，请参阅 BuildKit 页面。
团队的自动构建
当您在自己的用户帐户中创建自动构建存储库时，您可以启动、取消和重试构建，以及编辑和删除您自己的存储库。
如果您是所有者，这些相同的操作也适用于 Docker Hub 中的团队存储库。如果您是具有 写入 权限的团队成员，则可以在团队存储库中启动、取消和重试构建，但您无法编辑团队存储库设置或删除团队存储库。如果您的用户帐户具有 读取 权限，或者您是具有 读取 权限的团队成员，则可以查看构建配置，包括任何测试设置。
| 操作/权限 | 读取 | 写入 | 管理员 | 所有者 |
|---|---|---|---|---|
| 查看构建详细信息 | x | x | x | x |
| 启动、取消、重试 | x | x | x | |
| 编辑构建设置 | x | x | ||
| 删除构建 | x |
团队自动构建的服务用户
注意
只有所有者可以为团队设置自动构建。
当您为团队设置自动构建时，您会授予 Docker Hub 访问您的源代码存储库的权限，使用与特定用户帐户绑定的 OAuth。这意味着 Docker Hub 可以访问链接的源提供程序帐户可以访问的所有内容。
对于组织和团队，建议您创建专用服务帐户以授予对源提供程序的访问权限。这可以确保在单个用户的访问权限发生更改时，不会出现构建中断，并且单个用户的个人项目不会暴露给整个组织。
此服务帐户应该可以访问要构建的任何存储库，并且必须对源代码存储库具有管理访问权限，以便它可以管理部署密钥。如果需要，您可以将此帐户限制为仅对特定构建所需的特定一组存储库进行访问。
如果您使用链接的私有子模块（私有依赖项）构建存储库，则还需要将覆盖 SSH_PRIVATE 环境变量添加到与帐户关联的自动构建中。有关更多信息，请参阅 疑难解答
在您的源提供程序上创建一个服务用户帐户，并为其生成 SSH 密钥。
在您的组织中创建一个“构建”团队。
确保新的“构建”团队可以访问您需要构建的每个存储库和子模块。
转到存储库的 **设置** 页面。在 GitHub 上，将新的“构建”团队添加到 **合作者和团队** 列表中。在 Bitbucket 上，将“构建”团队添加到 **访问管理** 屏幕上的已批准用户列表中。
将服务用户添加到源提供程序上的“构建”团队。
以所有者身份登录 Docker Hub，切换到组织，并按照说明 链接到源代码存储库，使用服务帐户。
注意
您可能需要注销源代码提供程序上的个人帐户才能创建与服务帐户的链接。
可选：使用您生成的 SSH 密钥来设置使用私有子模块的任何构建，使用服务帐户和 上述说明。