Set up Automated Builds

预计阅读时间:17分钟

How Automated Builds work

Docker Hub 可以从外部存储库中的源代码自动构建镜像,并自动将构建的镜像推送到您的 Docker 存储库.

当您设置自动构建(也称为自动构建)时,您会创建要构建到 Docker 映像中的分支和标签的列表. 当您将代码推送到其中一个列出的图像标签的源代码分支(例如在 GitHub 中)时,推送使用 webhook 来触发新构建,从而生成 Docker 镜像. 然后将构建的映像推送到 Docker Hub 注册表.

Note

您仍然可以使用docker push将预构建的图像推送到配置了自动构建的存储库.

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

根据您的计划,您可能会获得并发构建,这意味着可以同时运行N个自动构建. N由您订阅的计划配置. 一旦N+1构建运行,任何其他构建都将排队等待稍后运行.

队列中未决构建的总数限制为 30,并且将丢弃更多请求. Pro 的并发构建数为 5,Team 和 Business 的并发构建数为 15.

An automated build dashboard

Configure automated build settings

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

可以将构建添加到现有存储库,或在创建存储库时添加.

  1. 存储库部分,单击存储库以查看其详细信息.

  2. 单击构建选项卡.

  3. If you are setting up automated builds for the first time, select the code repository service (GitHub or Bitbucket) where the image’s source code is stored. You may be redirected to the settings page to link the code repository service.

    否则,如果您正在编辑现有自动构建的构建设置,请单击配置自动构建.

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

    您可能需要从源代码提供程序中指定组织或用户(命名空间). 选择命名空间后,其源代码存储库将出现在选择存储库下拉列表中.

  5. (可选)启用自动测试.

  6. 查看默认构建规则,并可选择单击加号以添加和配置更多构建规则.

    构建规则控制 Docker Hub 从源代码存储库的内容构建到图像中的内容,以及生成的图像在 Docker 存储库中的标记方式.

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

  7. 对于每个分支或标签,启用或禁用Autobuild切换.

    只有启用了自动构建的分支或标签才会被构建、测试,并将生成的图像推送到存储库. 禁用自动构建的分支是出于测试目的而构建的(如果在存储库级别启用),但构建的 Docker 映像不会推送到存储库.

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

    如果您经常构建大型映像或具有许多依赖项,构建缓存可以节省时间. 您可能希望禁用构建缓存以确保在构建时解决所有依赖项,或者如果您有一个可以更快地在本地构建的大层.

  9. 单击保存以保存设置,或单击保存并构建以保存并运行初始测试.

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

Set up build rules

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

构建规则部分,输入一个或多个要构建的源.

对于每个来源:

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

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

    首次配置自动构建时,系统会为您设置默认构建规则. 此默认设置从名为master的源代码中的Branch构建,并创建一个带有latest标记的 Docker 映像.

    您还可以使用正则表达式来选择要构建的源分支或标签. 要了解更多信息,请参阅正则表达式.

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

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

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

Note

当 Docker Hub 从源代码存储库中提取分支时,它会执行浅层克隆(仅指定分支的尖端). 有关详细信息,请参阅Autobuild 和 Autotest 的高级选项.

Environment variables for builds

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

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

Note: The variables set on the build configuration screen are used during the build processes only and should not be confused with the environment values used by your service (for example to create service links).

Check your active builds

存储库构建的摘要显示在存储库常规选项卡和构建选项卡中. 构建选项卡还显示构建队列时间和持续时间的彩色条形图. 两个视图都显示存储库的任何标记的挂起、进行中、成功和失败的构建.

Active Builds

您可以从任一位置单击构建作业以查看其构建报告. 构建报告显示有关构建作业的信息,包括源存储库和分支(或标签)、构建持续时间、创建时间和位置以及构建发生的用户命名空间.

Build Report

Cancel or retry a build

当构建排队或运行时,"常规"选项卡和"构建"选项卡上的构建报告链接旁边会出现一个取消图标. 您还可以从构建报告页面或时间轴选项卡的构建日志显示中单击取消按钮.

list of builds showing the cancel icon

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

Timeline view showing the retry build button

Note

If you are viewing the build details for a repository that belongs to an Organization, the Cancel and Retry buttons only appear if you have Read & Write access to the repository.

Disable an automated build

每个分支或标签都启用了自动构建,并且可以轻松地禁用和重新启用. 当您只想手动构建一段时间时,您可能会这样做,例如当您在代码中进行重大重构时. 禁用自动构建不会禁用自动测试.

要禁用自动构建:

  1. Repositories页面中,单击一个存储库,然后单击Builds选项卡.

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

  3. 构建规则部分,找到您不再希望自动构建的分支或标签.

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

    禁用时切换变为灰色.

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

Advanced automated build options

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

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

Tag and Branch builds

您可以配置您的自动构建,以便推送到特定分支或标签触发构建.

  1. 构建规则部分,单击加号以添加更多要构建的源.

  2. 选择要构建的Source 类型tagbranch .

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

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

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

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

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

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

Set the build context and Dockerfile location

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

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

Note

如果您从Build context字段中删除默认路径/并将其留空,则构建系统将使用 Dockerfile 的路径作为构建上下文. 但是,为避免混淆,我们建议您指定完整路径.

您可以将Dockerfile 位置指定为相对于构建上下文的路径. 如果 Dockerfile 位于构建上下文路径的根目录,请将 Dockerfile 路径设置为/ . (如果构建上下文字段为空,则从源存储库的根目录设置 Dockerfile 的路径.)

Regexes and automated builds

您可以指定正则表达式 (regex),以便只构建匹配的分支或标签. 您还可以使用正则表达式的结果来创建应用于构建映像的 Docker 标记.

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

Build images with BuildKit

默认情况下,自动构建使用 BuildKit 构建系统. 如果要使用旧版 Docker 构建系统,请添加环境变量DOCKER_BUILDKIT=0 . 有关 BuildKit 的更多信息,请参阅带有 BuildKit 的构建映像页面.

Build repositories with linked private submodules

Docker Hub 在您的源代码存储库中设置了一个部署密钥,允许它克隆存储库并构建它; 但是,此密钥仅适用于单个特定代码存储库. 如果您的源代码存储库使用私有 Git 子模块(或要求您克隆其他私有存储库以进行构建),则 Docker Hub 无法访问这些额外的存储库,您的构建无法完成,并且您的构建时间线中会记录错误.

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

Note

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

  1. 生成仅用于构建的 SSH 密钥对,并将公钥添加到您的源代码提供者帐户.

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

  2. 将密钥对的私有部分复制到剪贴板.
  3. 在 Docker Hub 中,导航到已链接私有子模块的存储库的构建页面. (如有必要,请按照此处的步骤配置自动构建.)
  4. 在屏幕底部,单击Build Environment variables旁边的加号 ( + ).
  5. 输入SSH_PRIVATE作为新环境变量的名称.
  6. 将密钥对的私有部分粘贴到字段中.
  7. 单击SaveSave and Build以验证构建现在是否完成.

Note

您必须使用 git clone over SSH ( git@submodule.tld:some-submodule.git ) 而不是 HTTPS 来配置您的私有 git 子模块.

Autobuild for Teams

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

如果您是组织Owners团队的成员,这些相同的操作也可用于 Docker Hub 中的团队存储库. 如果您是具有write权限的团队成员,您可以在团队的存储库中启动、取消和重试构建,但您无法编辑团队存储库设置或删除团队存储库. 如果您的用户帐户具有read权限,或者您是具有read权限的团队成员,您可以查看构建配置,包括任何测试设置.

Action/Permission read write admin owner
查看构建详细信息 x x x x
开始、取消、重试   x x x
编辑构建设置     x x
删除构建       x

Service users for team autobuilds

注意:只有Owners团队的成员才能为团队设置自动构建.

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

对于组织和团队,我们建议创建一个专用服务帐户(或"机器用户")来授予对源提供者的访问权限. 这可确保不会随着单个用户的访问权限更改而中断构建,并且单个用户的个人项目不会暴露给整个组织.

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

如果您正在使用链接的私有子模块(私有依赖项)构建存储库,您还需要将覆盖SSH_PRIVATE环境变量添加到与帐户关联的自动构建中.

  1. 在您的源提供者上创建一个服务用户帐户,并为其生成 SSH 密钥.
  2. 在您的组织中创建一个"构建"团队.
  3. 确保新的"构建"团队可以访问您需要构建的每个存储库和子模块.

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

  4. 将服务用户添加到源提供者的"构建"团队.

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

    注意:您可能需要在源代码提供商上注销您的个人帐户才能创建到服务帐户的链接.

  6. 或者,使用您生成的 SSH 密钥来设置任何带有私有子模块的构建,使用服务帐户和上面的说明.

What’s Next?

Customize your build process

其他高级选项可用于自定义您的自动构建,包括实用程序环境变量、挂钩和构建阶段覆盖. 要了解更多信息,请参阅Autobuild 和 Autotest 的高级选项.

Add automated tests

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

Note

虽然自动测试功能会出于测试目的构建映像,但它不会将生成的映像推送到 Docker Hub.

automated, build, images, 码头工人中心

by  icopy.site