设置自动构建

预计阅读时间：17分钟

自动构建的工作方式

Docker Hub可以自动从外部存储库中的源代码构建映像，并将生成的映像自动推送到您的Docker存储库。

设置自动构建（也称为自动构建）时，将创建要构建到Docker映像中的分支和标签的列表。当您将代码推送到其中列出的图像标签之一的源代码分支（例如，在GitHub中）时，推送将使用Webhook触发新的构建，从而生成Docker图像。然后将构建的映像推送到Docker Hub注册表。

笔记

您仍然可以使用已docker push配置自动构建的方式将预构建的映像推送到存储库。

如果您配置了自动测试，则这些测试将在构建之后但在推送到注册表之前运行。您可以使用这些测试来创建一个持续集成工作流，其中无法通过测试的构建不会推送构建的映像。自动化测试不会自行将映像推送到注册表。在此处了解有关自动图像测试的更多信息。

根据您的计划，您可能会得到并行构建，这意味着N 可以同时运行自动构建。N由您订阅的计划配置。一旦N+1建立运行，任何额外的版本是排队等待稍后运行。

笔记

队列中未决构建的总数限制为30，其他请求将被丢弃。

配置自动构建设置

您可以在Docker Hub中配置存储库，以便每次您将新代码推送到源提供者时它们都会自动构建映像。如果您 配置了自动测试，则仅在测试成功时才推送新映像。

构建可以添加到现有存储库，也可以在创建存储库时添加。

1. 在“存储库”部分中，单击进入存储库以查看其详细信息。

2. 单击构建选项卡。

3. 如果您是第一次设置自动构建，请选择存储图像源代码的代码存储库服务（GitHub或Bitbucket）。您可能会重定向到设置页面以链接代码存储库服务。

   否则，如果您正在编辑现有自动构建的构建设置，请点击配置自动构建。

4. 选择要从中构建Docker映像的源存储库。

   您可能需要从源代码提供程序中指定组织或用户（名称空间）。选择命名空间后，其源代码存储库将显示在“选择存储库”下拉列表中。

5. （可选）启用自动测试。

6. 查看默认的构建规则，然后选择单击 加号以添加和配置更多构建规则。

   构建规则控制着Docker Hub从源代码存储库的内容构建到映像中的方式，以及如何在Docker存储库中标记生成的映像。

   为您设置了一个默认的构建规则，您可以对其进行编辑或删除。此默认集合从Branch您的源代码存储库中称为 构建master，并创建一个标记为的Docker映像latest。

7. 对于每个分支或标签，启用或禁用“自动构建”切换。

   仅构建，测试启用自动构建的分支或标记，并将结果映像推送到存储库。禁用自动构建的分支是出于测试目的而构建的（如果在存储库级别启用），但是构建的Docker映像不会推送到存储库。

8. 对于每个分支或标签，启用或禁用“构建缓存”切换。

   如果您频繁构建大型映像或具有许多依赖项，则生成缓存可以节省时间。您可能希望禁用构建缓存，以确保在构建时解决了所有依赖项，或者如果您有一个较大的层，可以更快地在本地构建。

9. 单击“保存”以保存设置，或单击“保存并生成”以保存并运行初始测试。

   一个webhook会自动添加到您的源代码存储库，以在每次推送时通知Docker Hub。只有推送到被列为一个或多个标签来源的分支才会触发构建。

设置构建规则

默认情况下，设置自动构建时，会为您创建一个基本的构建规则。此默认规则监视master源代码存储库中分支的更改，并将分支构建master为标记为的Docker映像 latest。

在“构建规则”部分中，输入一个或多个要构建的源。

对于每个来源：

• 选择Source类型以构建标签或 分支。这告诉构建系统在源代码存储库中寻找什么。

• 输入您要构建的Source分支或标签的名称。

  首次配置自动构建时，将为您设置默认构建规则。此默认集从Branch名为的源代码中 构建master，并创建一个标记为的Docker映像latest。

  您还可以使用正则表达式选择要构建的源分支或标记。要了解更多信息，请参阅 regexes。

• 输入标签以应用于从此源构建的Docker映像。

  如果配置了正则表达式来选择源，则可以引用捕获组并将其结果用作标记的一部分。要了解更多信息，请参阅 regexes。

• 将Dockerfile位置指定为相对于源代码存储库根目录的路径。（如果Dockerfile位于存储库根目录，请将此路径设置为/。）

笔记

当Docker Hub从源代码存储库中提取分支时，它将执行浅表克隆（仅指定分支的尖端）。有关更多信息，请参阅自动构建和自动测试的高级选项。

构建的环境变量

配置自动生成时，可以设置在生成过程中使用的环境变量的值。通过单击“构建环境变量”部分旁边的加号，然后输入变量名称和值来添加构建环境变量。

从Docker Hub UI设置变量值时，可以在hooks文件中设置的命令使用它们，但它们会被存储，以便只有有权admin访问Docker Hub存储库的用户才能看到其值。这意味着您可以使用它们安全地存储访问令牌或其他应保密的信息。

注意：在构建配置屏幕上设置的变量仅在构建过程中使用，不应与服务使用的环境值（例如，用于创建服务链接）相混淆。

检查您的活动版本

存储库构建的摘要同时显示在存储库的“常规” 选项卡和“构建”选项卡中。所述构建标签还显示生成队列时间和持续时间的彩色编码条形图。这两个视图都显示存储库中任何标记的挂起，进行中，成功和失败的构建。

在任一位置，您都可以单击构建作业以查看其构建报告。生成报告显示有关生成作业的信息，包括源存储库和分支（或标记），生成持续时间，创建时间和位置以及生成生成文件的用户名称空间。

取消或重试构建

当构建排队或正在运行时，“常规”选项卡和“构建”选项卡上的“构建报告”链接旁边会出现“取消”图标。您也可以从构建报告页面或“时间轴”选项卡的日志显示中单击“ 取消”按钮以进行构建。

如果构建失败，则“常规”和“构建”选项卡上的构建报告行旁边会出现一个“重试”图标，并且构建报告页面和时间轴日志也会显示“重试”按钮。

笔记

如果您正在查看属于组织的存储库的构建详细信息，则只有在您有权Read & Write访问该存储库的情况下，才会显示“取消”和“重试”按钮。

禁用自动构建

每个分支或标签都启用了自动构建，并且可以轻松禁用和重新启用。当您只想手工构建一段时间（例如在代码中进行大型重构时），可以执行此操作。禁用自动构建不会禁用自动测试。

要禁用自动构建：

1. 在“存储库”页面中，单击进入存储库，然后单击“构建”选项卡。

2. 单击配置自动构建以编辑存储库的构建设置。

3. 在“构建规则”部分中，找到不再要自动构建的分支或标记。

4. 单击配置行旁边的自动构建切换。

   禁用时，切换开关变为灰色。

5. 单击保存以保存您的更改。

先进的自动构建选项

至少需要一个由源分支（或标签）和目标Docker标签组成的构建规则来设置自动构建。您还可以更改构建查找Dockerfile的位置，设置构建使用文件的路径（构建上下文），设置要构建的多个静态标记或分支以及使用正则表达式（regexes）动态选择源代码来创建和创建动态标签。

所有这些选项都可以从每个存储库的“构建”配置屏幕中获得。点击库，从左侧导航栏中，单击要编辑的存储库的名称，单击构建选项卡，然后单击 配置自动的构建。

标签和分支构建

您可以配置自动构建，以便将其推送到特定分支或标签即可触发构建。

1. 在“构建规则”部分中，单击加号以添加更多要构建的源。

2. 选择要构建的Source类型：tag或branch。

   这告诉构建系统要在代码存储库中查找哪种类型的源。

3. 输入您要构建的Source分支或标签的名称。

   您可以输入名称，或使用正则表达式来匹配要构建的源分支或标记名称。要了解更多信息，请参阅 regexes。

4. 输入标签以应用于从此源构建的Docker映像。

   如果配置了正则表达式来选择源，则可以引用捕获组并将其结果用作标记的一部分。要了解更多信息，请参阅 regexes。

5. 对您设置的每个新构建规则重复步骤2到4。

设置构建上下文和Dockerfile位置

根据文件在源代码存储库中的排列方式，生成映像所需的文件可能不在存储库根目录中。如果是这种情况，您可以指定构建在其中查找文件的路径。

在构建上下文是路径所需的构建，相对于库的根目录中的文件。在构建上下文字段中输入这些文件的路径。输入/以将构建上下文设置为源代码存储库的根。

笔记

如果/从“构建上下文”字段中删除默认路径并将其保留为空白，则构建系统会将Dockerfile的路径用作构建上下文。但是，为避免混淆，建议您指定完整路径。

您可以将Dockerfile位置指定为相对于构建上下文的路径。如果Dockerfile位于构建上下文路径的根目录，请将Dockerfile路径设置为/。（如果构建上下文字段为空白，请从源存储库的根目录设置到Dockerfile的路径。）

正则表达式和自动构建

您可以指定正则表达式（regex），以便仅构建匹配的分支或标记。您还可以使用正则表达式的结果来创建应用于已构建映像的Docker标记。

您最多可以使用九个正则表达式捕获组（用括号括起来的表达式）来选择要构建的源，并使用来在Docker Tag字段中引用它们。{\1}{\9}

使用BuildKit生成图像

您可以通过在“ 配置自动构建设置”部分中设置DOCKER_BUILDKIT=1 环境变量来启用BuildKit构建器。 有关BuildKit的更多信息，请参考使用BuildKit生成映像。

使用链接的私有子模块构建存储库

Docker Hub在您的源代码存储库中设置了一个部署密钥，从而可以克隆该存储库并进行构建。但是，此密钥仅适用于单个特定的代码存储库。如果您的源代码存储库使用私有Git子模块（或要求您克隆其他私有存储库以进行构建），则Docker Hub无法访问这些其他存储库，您的构建无法完成，并且在构建时间线中记录了错误。

要解决此问题，您可以使用SSH_PRIVATE环境变量设置自动构建，以覆盖部署密钥，并授予Docker Hub的构建系统对存储库的访问权限。

笔记

如果您正在为团队使用自动构建，请改用以下过程，并为您的源代码提供者配置服务用户。您也可以为单个帐户执行此操作，以限制Docker Hub对您的源存储库的访问。

1. 生成仅用于构建的SSH密钥对，然后将公钥添加到源代码提供程序帐户。

   此步骤是可选的，但允许您在不删除其他访问权限的情况下撤消仅构建的密钥对。

2. 将密钥对的私有一半复制到剪贴板。
3. 在Docker Hub中，导航到已链接私有子模块的存储库的构建页面。（如果需要，请按照此处的步骤配置自动构建。）
4. 在屏幕底部，单击“构建环境变量”旁边的加号（+）。
5. 输入SSH_PRIVATE新环境变量的名称。
6. 将密钥对的私密部分粘贴到“值”字段中。
7. 单击“保存”，或单击“保存并构建”以确认构建现在已完成。

笔记

您必须通过SSH（git@submodule.tld:some-submodule.git）而非HTTPS使用git clone配置私有git子模块。

为团队自动构建

当您在自己的帐户名称空间中创建自动构建存储库时，可以启动，取消和重试构建，以及编辑和删除自己的存储库。

如果您是本组织Owners团队的成员，则这些相同的操作也可从Docker Hub的团队存储库中获得。如果您是拥有write权限的团队的成员，则可以在团队的存储库中启动，取消和重试构建，但是您不能编辑团队存储库设置或删除团队存储库。如果您的用户帐户具有read许可，或者您是具有read许可的团队成员，则可以查看构建配置，包括任何测试设置。

为团队自动构建服务的用户

注意：只有Owners团队成员才能为团队设置自动构建。

在为团队设置自动构建时，您可以使用绑定到特定用户帐户的OAuth来授予Docker Hub访问源代码存储库的权限。这意味着Docker Hub可以访问链接的源提供程序帐户可以访问的所有内容。

对于组织和团队，我们建议创建一个专用的服务帐户（或“机器用户”）以授予对源提供商的访问权限。这样可确保不会因个人用户的访问权限更改而中断构建，并且不会将个人用户的个人项目暴露给整个组织。

该服务帐户应有权访问要构建的任何存储库，并且必须对源代码存储库具有管理访问权，以便它可以管理部署密钥。如果需要，您可以将此帐户限制为仅特定构建所需的一组特定存储库。

如果要使用链接的私有子模块（私有依赖项）构建存储库，则还需要向SSH_PRIVATE与该帐户关联的自动构建中添加替代环境变量。

1. 在源提供者上创建一个服务用户帐户，并为其生成SSH密钥。
2. 在您的组织中创建一个“构建”团队。

3. 确保新的“构建”团队有权访问您需要构建的每个存储库和子模块。

   转到存储库的“设置”页面。在GitHub上，将新的“构建”团队添加到“协作者和团队”列表中。在Bitbucket上，将“构建”团队添加到“访问管理”屏幕上的批准用户列表中。

4. 将服务用户添加到源提供者的“构建”团队中。

5. 以Owners团队成员身份登录Docker Hub ，切换到组织，然后按照说明使用服务帐户链接到源代码存储库。

   注意：您可能需要注销源代码提供者上的个人帐户才能创建到服务帐户的链接。

6. （可选）使用服务帐户和上述说明，使用生成的SSH密钥设置带有私有子模块的任何内部版本。

下一步是什么？

自定义您的构建过程

其他高级选项可用于自定义自动化构建，包括实用程序环境变量，挂钩和构建阶段覆盖。要了解更多信息，请参阅自动构建和自动测试的高级选项。

添加自动化测试

要在推送映像之前测试代码，可以使用Docker Hub的Autotest功能，该功能与autobuild和autoredeploy无缝集成。

笔记

虽然自动测试功能会生成用于测试目的的映像，但不会将生成的映像推送到Docker Hub。