docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

hub: autobuild refresh (#21610) 

<!--Delete sections as needed -->

## Description

Quick refresh of autobuild content.

- Updated some linkTitles and weights to make the titles more scannable
in the nav and somewhat logically ordered.
- Updated capitalization to sentence case for consistency. 
  - `Automated builds`->`[Aa]utomated builds`
  - `Autobuild`->`[Aa]utobuild`
  - `Automated tests`->`[Aa]utomated tests`
  - `Autotest`->`[Aa]utotest`
- Updated note formatting.
- Fixed some vale nags.
  - `above`->`previous`
  - `click`->`select`

Did a `git mv` with the following files, but I think the similar file
names caused everything to be flagged as new/deleted rather than just
renamed. Not planning to do a deeper refresh of the existing content at
this time.

- Renamed `_index.md` to `setup.md`
- Renamed `how-builds-work.md` to `_index.md`


https://deploy-preview-21610--docsdocker.netlify.app/docker-hub/repos/manage/builds/

## Related issues or tickets

ENGDOCS-2351

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Editorial review

Signed-off-by: Craig <craig.osterhout@docker.com>
This commit is contained in:
Craig Osterhout 2025-01-08 13:27:51 -08:00 committed by GitHub
parent 2db1648b57
commit c5b31325ae
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 342 additions and 334 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
_vale/config/vocabularies/Docker/accept.txt
View File

@ -3,7 +3,6 @@ Amazon
Anchore
Apple
Artifactory
Autotest
Azure
Btrfs
BuildKit
@ -100,6 +99,9 @@ Zsh
[Aa]nonymized?
[Aa]utobuild
[Aa]llowlist
[Aa]utobuilds?
[Aa]utotests?
[Bb]uildx
[Bb]uildpack(s)?
[Bb]uildx
[Cc]odenames?
@ -126,6 +128,7 @@ Zsh
[Pp]roxied
[Pp]roxying
[Rr]eal-time
[Rr]egex(es)?
[Rr]untimes?
[Ss]andbox(ed)?
[Ss]eccomp

309
content/manuals/docker-hub/repos/manage/builds/_index.md
View File

@ -1,13 +1,10 @@
---
description: Set up Automated builds
keywords: automated, build, images, Docker Hub
title: Set up Automated Builds
linkTitle: Automated builds
description: how automated builds work
keywords: docker hub, automated builds
title: Automated builds
weight: 90
aliases:
- /docker-hub/builds/automated-build/
- /docker-hub/builds/classic/
- /docker-hub/builds/
- /docker-hub/builds/how-builds-work/
---
> [!NOTE]
@ -15,287 +12,33 @@ aliases:
> Automated builds require a
> Docker Pro, Team, or Business subscription.
This page contains information on:
- [Configuring Automated builds](#configure-automated-builds)
- [Advanced Automated build options](#advanced-automated-build-options)
- [Automated builds for teams](#autobuild-for-teams)
Docker Hub can automatically build images from source code in an external
repository and automatically push the built image to your Docker repositories.
## Configure Automated builds
![An automated build dashboard](images/index-dashboard.png)
You can configure repositories in Docker Hub so that they automatically
build an image each time you push new code to your source provider. If you have
[automated tests](automated-testing.md) configured, the new image is only pushed
when the tests succeed.
1. From the **Repositories** section, select a repository to view its details.
2. Select the **Builds** tab.
3. Select either GitHub or Bitbucket to connect where the image's source code is stored.
> Note
>
> You may be redirected to the settings page to [link](link-source.md) the
> code repository service. Otherwise, if you are editing the build settings
> for an existing automated build, click **Configure automated builds**.
4. Select the **source repository** to build the Docker images from.
> Note
>
> You might need to specify an organization or user from
> the source code provider. Once you select a user, source code
> repositories appear in the **Select repository** drop-down list.
5. Optional: Enable [autotests](automated-testing.md#enable-automated-tests-on-a-repository).
6. Review the default **Build Rules**.
Build rules control what Docker Hub builds into images from the contents
of the source code repository, and how the resulting images are tagged
within the Docker repository.
A default build rule is set up for you, which you can edit or delete. This
default rule sets builds from the `Branch` in your source code repository called
`master` or `main`, and creates a Docker image tagged with `latest`. For more information, see [set up build rules](#set-up-build-rules)
7. Optional: Select the **plus** icon to add and [configure more build rules](#set-up-build-rules).
8. For each branch or tag, enable or disable the **Autobuild** toggle.
Only branches or tags with autobuild enabled are built, tested, and have
the resulting image pushed to the repository. Branches with autobuild
disabled are built for test purposes (if enabled at the repository
level), but the built Docker image isn't pushed to the repository.
9. For each branch or tag, enable or disable the **Build Caching** toggle.
[Build caching](/manuals/build/building/best-practices.md#leverage-build-cache)
can save time if you are building a large image frequently or have
many dependencies. Leave the build caching disabled to
make sure all of your dependencies are resolved at build time, or if
you have a large layer that's quicker to build locally.
10. Select **Save** to save the settings, or select **Save and build** to save and
run an initial test.
> Note
>
> A webhook is automatically added to your source code repository to notify
> Docker Hub on every push. Only pushes to branches that are listed as the
> source for one or more tags, trigger a build.
### Set up build rules
By default when you set up Automated builds, a basic build rule is created for you.
This default rule watches for changes to the `master` or `main` branch in your source code
repository, and builds the `master` or `main` branch into a Docker image tagged with
`latest`.
In the **Build Rules** section, enter one or more sources to build.
For each source:
* Select the **Source type** to build either a tag or a branch. This
tells the build system what to look for in the source code repository.
* Enter the name of the **Source** branch or tag you want to build.
The first time you configure Automated builds, a default build rule is set up
for you. This default set builds from the `Branch` in your source code called
`master`, and creates a Docker image tagged with `latest`.
You can also use a regex to select which source branches or tags to build.
To learn more, see
[regexes](#regexes-and-automated-builds).
* Enter the tag to apply to Docker images built from this source.
If you configured a regex to select the source, you can reference the
capture groups and use its result as part of the tag. To learn more, see
[regexes](#regexes-and-automated-builds).
* Specify the **Dockerfile location** as a path relative to the root of the source code repository. If the Dockerfile is at the repository root, leave this path set to `/`.
When you set up automated builds, also called autobuilds, you create a list of
branches and tags that you want to build into Docker images. When you push code
to a source-code branch, for example in GitHub, for one of those listed image
tags, the push uses a webhook to trigger a new build, which produces a Docker
image. The built image is then pushed to Docker Hub.
> [!NOTE]
>
> When Docker Hub pulls a branch from a source code repository, it performs a
> shallow clone - only the tip of the specified branch. Refer to
> [Advanced options for Autobuild and Autotest](advanced.md#source-repository-or-branch-clones)
> for more information.
> You can still use `docker push` to push pre-built images to
repositories with automated builds configured.
### Environment variables for builds
If you have automated tests configured, these run after building, but before
pushing to the registry. You can use these tests to create a continuous
integration workflow where a build that fails its tests doesn't push the built
image. Automated tests don't push images to the registry on their own. [Learn about automated image testing](automated-testing.md).
You can set the values for environment variables used in your build processes
when you configure an automated build. Add your build environment variables by
selecting the **plus** icon next to the **Build environment variables** section, and
then entering a variable name and the value.
Depending on your [subscription](https://www.docker.com/pricing),
you may get concurrent builds, which means that `N` autobuilds can be run at the
same time. `N` is configured according to your subscription. Once `N+1` builds
are running, any additional builds go into a queue to be run later.
When you set variable values from the Docker Hub UI, you can use them by the
commands you set in `hooks` files. However, they're stored so that only users who have `admin` access to the Docker Hub repository can see their values. This
means you can use them to store access tokens or other information that
should remain secret.
> [!NOTE]
>
> The variables set on the build configuration screen are used during
> the build processes only and shouldn't get confused with the environment
> values used by your service, for example to create service links.
## Advanced automated build options
At the minimum you need a build rule composed of a source branch, or tag, and a
destination Docker tag to set up an automated build. You can also:
- Change where the build looks for the Dockerfile
- Set a path to the files the build should use (the build context)
- Set up multiple static tags or branches to build from
- Use regular expressions (regexes) to dynamically select source code to build and
create dynamic tags
All of these options are available from the **Build configuration** screen for
each repository. Select **Repositories** from the left navigation, and select the name of the repository you want to edit. Select the **Builds** tab, and then select **Configure Automated builds**.
### Tag and branch builds
You can configure your automated builds so that pushes to specific branches or tags triggers a build.
1. In the **Build Rules** section, select the **plus** icon to add more sources to build.
2. Select the **Source type** to build either a tag or a branch.
> Note
>
> This tells the build system what type of source to look for in the code
> repository.
3. Enter the name of the **Source** branch or tag you want to build.
> Note
>
> You can enter a name, or use a regex to match which source branch or tag
> names to build. To learn more, see [regexes](index.md#regexes-and-automated-builds).
4. Enter the tag to apply to Docker images built from this source.
> Note
>
> If you configured a regex to select the source, you can reference the
> capture groups and use its result as part of the tag. To learn more, see
> [regexes](index.md#regexes-and-automated-builds).
5. Repeat steps 2 through 4 for each new build rule you set up.
### Set the build context and Dockerfile location
Depending on how you arrange the files in your source code repository, the
files required to build your images may not be at the repository root. If that's
the case, you can specify a path where the build looks for the files.
The build context is the path to the files needed for the build, relative to
the root of the repository. Enter the path to these files in the **Build context** field. Enter `/` to set the build context as the root of the source code repository.
> [!NOTE]
>
> If you delete the default path `/` from the **Build context** field and leave
> it blank, the build system uses the path to the Dockerfile as the build
> context. However, to avoid confusion it's recommended that you specify the
> complete path.
You can specify the **Dockerfile location** as a path relative to the build
context. If the Dockerfile is at the root of the build context path, leave the
Dockerfile path set to `/`. If the build context field is blank, set the path
to the Dockerfile from the root of the source repository.
### Regexes and Automated builds
You can specify a regular expression (regex) so that only matching branches or
tags are built. You can also use the results of the regex to create the Docker
tag that's applied to the built image.
You can use up to nine regular expression capture groups, or expressions enclosed in parentheses, to select a source to build, and reference
these in the **Docker Tag** field using `{\1}` through `{\9}`.
<!-- Capture groups Not a priority
#### Regex example: build from version number branch and tag with version number
You could also use capture groups to build and label images that come from various
sources. For example, you might have
`/(alice|bob)-v([0-9.]+)/` -->
### Build images with BuildKit
Autobuilds use the BuildKit build system by default. If you want to use the legacy
Docker build system, add the [environment variable](index.md#environment-variables-for-builds)
`DOCKER_BUILDKIT=0`. Refer to the [BuildKit](/manuals/build/buildkit/_index.md)
page for more information on BuildKit.
## Autobuild for teams
When you create an automated build repository in your own user account, you
can start, cancel, and retry builds, and edit and delete your own repositories.
These same actions are also available for team repositories from Docker Hub if
you are an owner. If you are a member of a
team with `write` permissions you can start, cancel, and retry builds in your
team's repositories, but you cannot edit the team repository settings or delete
the team repositories. If your user account has `read` permission, or if you're
a member of a team with `read` permission, you can view the build configuration
including any testing settings.
| Action/Permission | Read | Write | Admin | Owner |
| --------------------- | ---- | ----- | ----- | ----- |
| view build details | x | x | x | x |
| start, cancel, retry | | x | x | x |
| edit build settings | | | x | x |
| delete build | | | | x |
### Service users for team autobuilds
> [!NOTE]
>
> Only owners can set up Automated builds for teams.
When you set up Automated builds for teams, you grant Docker Hub access to
your source code repositories using OAuth tied to a specific user account. This
means that Docker Hub has access to everything that the linked source provider
account can access.
For organizations and teams, it's recommended you create a dedicated service account to grant access to the source provider. This ensures that no
builds break as individual users' access permissions change, and that an
individual user's personal projects aren't exposed to an entire organization.
This service account should have access to any repositories to be built,
and must have administrative access to the source code repositories so it can
manage deploy keys. If needed, you can limit this account to only a specific
set of repositories required for a specific build.
If you are building repositories with linked private submodules (private
dependencies), you also need to add an override `SSH_PRIVATE` environment
variable to automated builds associated with the account. For more information, see [Troubleshoot](troubleshoot.md#build-repositories-with-linked-private-submodules)
1. Create a service user account on your source provider, and generate SSH keys for it.
2. Create a "build" team in your organization.
3. Ensure that the new "build" team has access to each repository and submodule you need to build.
Go to the repository's **Settings** page. On GitHub, add the new "build" team
to the list of **Collaborators and Teams**. On Bitbucket, add the "build" team
to the list of approved users on the **Access management** screen.
4. Add the service user to the "build" team on the source provider.
5. Sign in to Docker Hub as an owner, switch to the organization, and follow the instructions to [link to source code repository](link-source.md) using the service account.
> [!NOTE]
>
> You may need to log out of your individual account on the source code provider to create the link to the service account.
6. Optional: Use the SSH keys you generated to set up any builds with private submodules, using the service account and [the instructions above](troubleshoot.md#build-repositories-with-linked-private-submodules).
## What's Next?
- [Customize your build process](advanced.md) with environment variables, hooks, and more
- [Add automated tests](automated-testing.md)
- [Manage your builds](manage-builds.md)
- [Troubleshoot](troubleshoot.md)
The maximum number of pending builds in the queue is 30 and Docker Hub discards further
requests. The number of concurrent builds for Pro is 5 and
for Team and Business is 15.
Automated builds can handle images of up to 10 GB in size.

4
content/manuals/docker-hub/repos/manage/builds/advanced.md
View File

@ -1,7 +1,9 @@
---
description: Automated builds
keywords: automated, build, images
title: Advanced options for Autobuild and Autotest
title: Advanced options for autobuild and autotest
linkTitle: Advanced options
weight: 40
aliases:
- /docker-hub/builds/advanced/
---

13
content/manuals/docker-hub/repos/manage/builds/automated-testing.md
View File

@ -2,6 +2,7 @@
description: Automated tests
keywords: Automated, testing, repository
title: Automated repository tests
weight: 30
aliases:
- /docker-hub/builds/automated-testing/
---
@ -36,7 +37,7 @@ services:
command: run_tests.sh
```
The example above builds the repository, and runs the `run_tests.sh` file inside
The previous example builds the repository, and runs the `run_tests.sh` file inside
a container using the built image.
You can define any number of linked services in this file. The only requirement
@ -58,18 +59,18 @@ to further customize your test behavior.
> [!NOTE]
>
> If you enable Automated builds, they also run any tests defined
> If you enable automated builds, they also run any tests defined
in the `test.yml` files.
## Enable Automated tests on a repository
## Enable automated tests on a repository
To enable testing on a source code repository, you must first create an
associated build-repository in Docker Hub. Your `Autotest` settings are
configured on the same page as [automated builds](index.md), however
you do not need to enable Autobuilds to use `Autotest`. Autobuild is enabled per
you do not need to enable autobuilds to use autotest. Autobuild is enabled per
branch or tag, and you do not need to enable it at all.
Only branches that are configured to use Autobuild push images to the
Only branches that are configured to use autobuild push images to the
Docker repository, regardless of the Autotest settings.
1. Sign in to Docker Hub and select **Repositories**.
@ -80,7 +81,7 @@ Docker repository, regardless of the Autotest settings.
4. Select **Configure automated builds**.
5. Configure the automated build settings as explained in [Automated Builds](index.md).
5. Configure the automated build settings as explained in [Automated builds](index.md).
At minimum you must configure:

43
content/manuals/docker-hub/repos/manage/builds/how-builds-work.md
View File

@ -1,43 +0,0 @@
---
description: how automated builds work
keywords: docker hub, automated builds
title: How Automated builds work
aliases:
- /docker-hub/builds/how-builds-work/
---
> [!NOTE]
>
> Automated builds require a
> Docker Pro, Team, or Business subscription.
Docker Hub can automatically build images from source code in an external
repository and automatically push the built image to your Docker repositories.
![An automated build dashboard](images/index-dashboard.png)
When you set up Automated builds, also called autobuilds, you create a list of
branches and tags that you want to build into Docker images. When you push code
to a source-code branch, for example in GitHub, for one of those listed image
tags, the push uses a webhook to trigger a new build, which produces a Docker
image. The built image is then pushed to Docker Hub.
> [!NOTE]
>
> You can still use `docker push` to push pre-built images to
repositories with Automated builds configured.
If you have automated tests configured, these run after building but before
pushing to the registry. You can use these tests to create a continuous
integration workflow where a build that fails its tests doesn't push the built
image. Automated tests don't push images to the registry on their own. [Learn about automated image testing](automated-testing.md).
Depending on your [subscription](https://www.docker.com/pricing),
you may get concurrent builds, which means that `N` autobuilds can be run at the
same time. `N` is configured according to your subscription. Once `N+1` builds
are running, any additional builds go into a queue to be run later.
The maximum number of pending builds in the queue is 30 and Docker Hub discards further
requests. The number of concurrent builds for Pro is 5 and
for Team and Business is 15.
Automated builds can handle images of up to 10 GB in size.

2
content/manuals/docker-hub/repos/manage/builds/link-source.md
View File

@ -3,6 +3,8 @@ description: Link to GitHub and BitBucket
keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, trusted,
builds, trusted builds, automated builds, GitHub
title: Configure automated builds from GitHub and BitBucket
linkTitle: Link accounts
weight: 20
aliases:
- /docker-hub/github/
- /docker-hub/bitbucket/

299
content/manuals/docker-hub/repos/manage/builds/setup.md Normal file
View File

@ -0,0 +1,299 @@
---
description: Set up automated builds
keywords: automated, build, images, Docker Hub
title: Set up automated builds
linkTitle: Set up
weight: 10
aliases:
- /docker-hub/builds/automated-build/
- /docker-hub/builds/classic/
- /docker-hub/builds/
---
> [!NOTE]
>
> Automated builds require a
> Docker Pro, Team, or Business subscription.
## Configure automated builds
You can configure repositories in Docker Hub so that they automatically
build an image each time you push new code to your source provider. If you have
[automated tests](automated-testing.md) configured, the new image is only pushed
when the tests succeed.
1. From the **Repositories** section, select a repository to view its details.
2. Select the **Builds** tab.
3. Select either GitHub or Bitbucket to connect where the image's source code is stored.
> [!NOTE]
>
> You may be redirected to the settings page to [link](link-source.md) the
> code repository service. Otherwise, if you are editing the build settings
> for an existing automated build, select **Configure automated builds**.
4. Select the **source repository** to build the Docker images from.
> [!NOTE]
>
> You might need to specify an organization or user from
> the source code provider. Once you select a user, source code
> repositories appear in the **Select repository** drop-down list.
5. Optional. Enable [autotests](automated-testing.md#enable-automated-tests-on-a-repository).
6. Review the default **Build Rules**.
Build rules control what Docker Hub builds into images from the contents
of the source code repository, and how the resulting images are tagged
within the Docker repository.
A default build rule is set up for you, which you can edit or delete. This
default rule sets builds from the `Branch` in your source code repository
called `master` or `main`, and creates a Docker image tagged with `latest`.
For more information, see [set up build rules](#set-up-build-rules).
7. Optional. Select the **plus** icon to add and [configure more build rules](#set-up-build-rules).
8. For each branch or tag, enable or disable the **Autobuild** toggle.
Only branches or tags with autobuild enabled are built, tested, and have
the resulting image pushed to the repository. Branches with autobuild
disabled are built for test purposes (if enabled at the repository
level), but the built Docker image isn't pushed to the repository.
9. For each branch or tag, enable or disable the **Build Caching** toggle.
[Build caching](/manuals/build/building/best-practices.md#leverage-build-cache)
can save time if you are building a large image frequently or have
many dependencies. Leave the build caching disabled to
make sure all of your dependencies are resolved at build time, or if
you have a large layer that's quicker to build locally.
10. Select **Save** to save the settings, or select **Save and build** to save and
run an initial test.
> [!NOTE]
>
> A webhook is automatically added to your source code repository to notify
> Docker Hub on every push. Only pushes to branches that are listed as the
> source for one or more tags, trigger a build.
### Set up build rules
By default when you set up automated builds, a basic build rule is created for you.
This default rule watches for changes to the `master` or `main` branch in your source code
repository, and builds the `master` or `main` branch into a Docker image tagged with
`latest`.
In the **Build Rules** section, enter one or more sources to build.
For each source:
* Select the **Source type** to build either a tag or a branch. This
tells the build system what to look for in the source code repository.
* Enter the name of the **Source** branch or tag you want to build.
The first time you configure automated builds, a default build rule is set up
for you. This default set builds from the `Branch` in your source code called
`master`, and creates a Docker image tagged with `latest`.
You can also use a regex to select which source branches or tags to build.
To learn more, see
[regexes](#regexes-and-automated-builds).
* Enter the tag to apply to Docker images built from this source.
If you configured a regex to select the source, you can reference the
capture groups and use its result as part of the tag. To learn more, see
[regexes](#regexes-and-automated-builds).
* Specify the **Dockerfile location** as a path relative to the root of the source code repository. If the Dockerfile is at the repository root, leave this path set to `/`.
> [!NOTE]
>
> When Docker Hub pulls a branch from a source code repository, it performs a
> shallow clone - only the tip of the specified branch. Refer to
> [Advanced options for autobuild and autotest](advanced.md#source-repository-or-branch-clones)
> for more information.
### Environment variables for builds
You can set the values for environment variables used in your build processes
when you configure an automated build. Add your build environment variables by
selecting the **plus** icon next to the **Build environment variables** section, and
then entering a variable name and the value.
When you set variable values from the Docker Hub UI, you can use them by the
commands you set in `hooks` files. However, they're stored so that only users who have `admin` access to the Docker Hub repository can see their values. This
means you can use them to store access tokens or other information that
should remain secret.
> [!NOTE]
>
> The variables set on the build configuration screen are used during
> the build processes only and shouldn't get confused with the environment
> values used by your service, for example to create service links.
## Advanced automated build options
At the minimum you need a build rule composed of a source branch, or tag, and a
destination Docker tag to set up an automated build. You can also:
- Change where the build looks for the Dockerfile
- Set a path to the files the build should use (the build context)
- Set up multiple static tags or branches to build from
- Use regular expressions (regexes) to dynamically select source code to build and
create dynamic tags
All of these options are available from the **Build configuration** screen for
each repository. Select **Repositories** from the left navigation, and select the name of the repository you want to edit. Select the **Builds** tab, and then select **Configure Automated builds**.
### Tag and branch builds
You can configure your automated builds so that pushes to specific branches or tags triggers a build.
1. In the **Build Rules** section, select the **plus** icon to add more sources to build.
2. Select the **Source type** to build either a tag or a branch.
> [!NOTE]
>
> This tells the build system what type of source to look for in the code
> repository.
3. Enter the name of the **Source** branch or tag you want to build.
> [!NOTE]
>
> You can enter a name, or use a regex to match which source branch or tag
> names to build. To learn more, see [regexes](index.md#regexes-and-automated-builds).
4. Enter the tag to apply to Docker images built from this source.
> [!NOTE]
>
> If you configured a regex to select the source, you can reference the
> capture groups and use its result as part of the tag. To learn more, see
> [regexes](index.md#regexes-and-automated-builds).
5. Repeat steps 2 through 4 for each new build rule you set up.
### Set the build context and Dockerfile location
Depending on how you arrange the files in your source code repository, the
files required to build your images may not be at the repository root. If that's
the case, you can specify a path where the build looks for the files.
The build context is the path to the files needed for the build, relative to
the root of the repository. Enter the path to these files in the **Build context** field. Enter `/` to set the build context as the root of the source code repository.
> [!NOTE]
>
> If you delete the default path `/` from the **Build context** field and leave
> it blank, the build system uses the path to the Dockerfile as the build
> context. However, to avoid confusion it's recommended that you specify the
> complete path.
You can specify the **Dockerfile location** as a path relative to the build
context. If the Dockerfile is at the root of the build context path, leave the
Dockerfile path set to `/`. If the build context field is blank, set the path
to the Dockerfile from the root of the source repository.
### Regexes and automated builds
You can specify a regular expression (regex) so that only matching branches or
tags are built. You can also use the results of the regex to create the Docker
tag that's applied to the built image.
You can use up to nine regular expression capture groups, or expressions enclosed in parentheses, to select a source to build, and reference
these in the **Docker Tag** field using `{\1}` through `{\9}`.
<!-- Capture groups Not a priority
#### Regex example: build from version number branch and tag with version number
You could also use capture groups to build and label images that come from various
sources. For example, you might have
`/(alice|bob)-v([0-9.]+)/` -->
### Build images with BuildKit
Autobuilds use the BuildKit build system by default. If you want to use the legacy
Docker build system, add the [environment variable](index.md#environment-variables-for-builds)
`DOCKER_BUILDKIT=0`. Refer to the [BuildKit](/manuals/build/buildkit/_index.md)
page for more information on BuildKit.
## Autobuild for teams
When you create an automated build repository in your own user account, you
can start, cancel, and retry builds, and edit and delete your own repositories.
These same actions are also available for team repositories from Docker Hub if
you are an owner. If you are a member of a
team with `write` permissions you can start, cancel, and retry builds in your
team's repositories, but you cannot edit the team repository settings or delete
the team repositories. If your user account has `read` permission, or if you're
a member of a team with `read` permission, you can view the build configuration
including any testing settings.
| Action/Permission | Read | Write | Admin | Owner |
| --------------------- | ---- | ----- | ----- | ----- |
| view build details | x | x | x | x |
| start, cancel, retry | | x | x | x |
| edit build settings | | | x | x |
| delete build | | | | x |
### Service users for team autobuilds
> [!NOTE]
>
> Only owners can set up automated builds for teams.
When you set up automated builds for teams, you grant Docker Hub access to
your source code repositories using OAuth tied to a specific user account. This
means that Docker Hub has access to everything that the linked source provider
account can access.
For organizations and teams, it's recommended you create a dedicated service account to grant access to the source provider. This ensures that no
builds break as individual users' access permissions change, and that an
individual user's personal projects aren't exposed to an entire organization.
This service account should have access to any repositories to be built,
and must have administrative access to the source code repositories so it can
manage deploy keys. If needed, you can limit this account to only a specific
set of repositories required for a specific build.
If you are building repositories with linked private submodules (private
dependencies), you also need to add an override `SSH_PRIVATE` environment
variable to automated builds associated with the account. For more information, see [Troubleshoot](troubleshoot.md#build-repositories-with-linked-private-submodules)
1. Create a service user account on your source provider, and generate SSH keys for it.
2. Create a "build" team in your organization.
3. Ensure that the new "build" team has access to each repository and submodule you need to build.
1. On GitHub or Bitbucket, go to the repository's **Settings** page.
2. Add the new "build" team to the list of approved users.
- GitHub: Add the team in **Collaborators and Teams**.
- Bitbucket: Add the team in **Access management**.
4. Add the service user to the "build" team on the source provider.
5. Sign in to Docker Hub as an owner, switch to the organization, and follow the instructions to [link to source code repository](link-source.md) using the service account.
> [!NOTE]
>
> You may need to sign out of your individual account on the source code provider to create the link to the service account.
6. Optional. Use the SSH keys you generated to set up any builds with private submodules, using the service account and [the previous instructions](troubleshoot.md#build-repositories-with-linked-private-submodules).
## What's Next?
- [Customize your build process](advanced.md) with environment variables, hooks, and more
- [Add automated tests](automated-testing.md)
- [Manage your builds](manage-builds.md)
- [Troubleshoot](troubleshoot.md)

1
content/manuals/docker-hub/repos/manage/builds/troubleshoot.md
View File

@ -3,6 +3,7 @@ title: Troubleshoot your autobuilds
description: How to troubleshoot Automated builds
keywords: docker hub, troubleshoot, automated builds, autobuilds
tags: [ Troubleshooting ]
linkTitle: Troubleshoot
aliases:
- /docker-hub/builds/troubleshoot/
---