Skip to content

Commit 231a83e

Browse files
craig-osterhoutcraig-osterhout
authored
hub: add migrate autobuilds (docker#23725)
<!--Delete sections as needed --> ## Description Added topic to help users migrate from autobuilds to github actions or bitbucket pipelines. https://deploy-preview-23725--docsdocker.netlify.app/docker-hub/repos/manage/builds/migrate/ ## Related issues or tickets ENGDOCS-3110 ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
1 parent 8c0e35e commit 231a83e

3 files changed

Lines changed: 189 additions & 0 deletions

File tree

‎_vale/config/vocabularies/Docker/accept.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -312,6 +312,7 @@ Zsh
312312
[Pp]roxied
313313
[Pp]roxying
314314
[pP]yright
315+
[Rr]eadme
315316
[Rr]eal-time
316317
[Rr]egex(es)?
317318
[Rr]untimes?

‎content/manuals/docker-hub/repos/manage/builds/images/autobuild-example.png‎

86.1 KB
Loading

‎content/manuals/docker-hub/repos/manage/builds/migrate.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
description: Migrate from Autobuilds to CI/CD workflows
3+
keywords: automated builds, autobuilds, migration, github actions, bitbucket pipelines
4+
title: Migrate from Autobuilds
5+
linkTitle: Migrate
6+
weight: 80
7+
---
8+
9+
This guide explains how to migrate your Docker Hub Autobuilds setup to
10+
Continuous Integration (CI) workflows, focusing on GitHub Actions and Bitbucket
11+
Pipelines as these are the built-in CI services for the two version control
12+
services supported via Autobuilds.
13+
14+
## Step 1: Create access tokens
15+
16+
To grant your CI workflows the ability to pull and push images to and from
17+
Docker Hub, you first need to create access tokens:
18+
19+
- For a personal repository: Create a [Personal
20+
Access Token](../../../../security/access-tokens.md) with **Read & Write**
21+
permissions.
22+
23+
- For an organization repository: Create an [Organization Access
24+
Token](../../../../enterprise/security/access-tokens.md) with the following
25+
permissions:
26+
- **Read public repositories**
27+
- **Image Pull** on any private repositories that the build needs to pull from
28+
- **Image Push** on the repository that the built image will be pushed to
29+
30+
The same token can be used for all CI workflows under the account's namespace
31+
provided it has adequate permissions to all relevant Docker Hub repositories.
32+
33+
Store the token securely in a password manager or your CI/CD platform's secrets
34+
manager. Never commit tokens to source code repositories.
35+
36+
## Step 2: Extract your Autobuilds configuration
37+
38+
For each Docker Hub repository currently configured to use Autobuilds, you need
39+
to extract its configuration to set up your CI workflows to duplicate the
40+
existing functionality. The only way to extract the configuration is via the
41+
Docker Hub web interface.
42+
43+
1. Sign in to [Docker Hub](https://hub.docker.com).
44+
45+
2. Navigate to your repository by going to **My Hub** > ***Your namespace*** >
46+
**Repositories** > ***Your Repository***.
47+
48+
3. Go to the **Builds** tab and select **Configure automated builds**.
49+
50+
If there is no existing build configuration, then this repository is not
51+
configured for Autobuilds.
52+
53+
4. Note the following configuration details:
54+
55+
- **Source Repository**: The GitHub or Bitbucket repository. The organization
56+
is the namespace and the repository is the repository name. This is where
57+
you need to add your workflow.
58+
59+
- **Autotest**: If Autotest is enabled for Pull Requests (either internal
60+
only or internal and external), then extra steps are needed in your
61+
workflow to run the Autotest step.
62+
63+
- **Repository Links**: Not supported and can be ignored. If chain builds are
64+
required, see the documentation for your CI service on how to chain builds
65+
together.
66+
67+
- **Build Rules**: Specify the triggers, tags, and paths of your builds.
68+
Ignore any entry where **Autobuild** is toggled off.
69+
70+
- **Build Environment Variables**: User-defined variables injected as
71+
environment variables into your build. You need to add these to your
72+
workflow. If the environment variables contain secrets, add them to your CI
73+
service's secrets manager. Then update your Dockerfile or build scripts to
74+
reference these secrets using your CI platform's syntax. See your CI
75+
service documentation on how to handle secrets.
76+
77+
### Example configuration
78+
79+
The following image shows an example Autobuilds configuration.
80+
81+
![Example Autobuilds configuration](./images/autobuild-example.png)
82+
83+
Based on the pictured example, you would note the following items for this
84+
Autobuilds configuration:
85+
86+
- Source code repository: GitHub repository `docker/docker-rust-hello`
87+
- Autotest: Disabled
88+
- Build rule 1: Build and push the image with tag `latest` when a new commit to
89+
the `main` branch is detected. The Dockerfile is at `./Dockerfile` and the
90+
build context is the root of the cloned code.
91+
- Build rule 2: Build and push the image with tag `v{\1}` when a new commit
92+
to a tag matching the regex `^v([0-9.]+)$` is detected. The Dockerfile is at
93+
`./Dockerfile` and the build context is the root of the cloned code.
94+
- Environment variable: Key `ENV_KEY` with value `ENV_VALUE`
95+
96+
## Step 3: Migrate to your CI/CD platform
97+
98+
Select the tab that matches your source code repository hosting platform.
99+
100+
{{< tabs >}}
101+
{{< tab name="GitHub Actions" >}}
102+
103+
If your source code repository is hosted on GitHub, see the [Docker
104+
Autobuilds example repository](https://github.com/docker/autobuilds-actions).
105+
106+
All files except those under the `.github/workflows` directory are for example
107+
purposes only.
108+
109+
The repository's readme details how to migrate from Autobuilds to GitHub Actions
110+
using one of the two provided workflows:
111+
112+
- The `simple-build` workflow builds and pushes a Docker image to your Docker
113+
Hub repository.
114+
- The `full-autobuilds` workflow contains all the steps commonly used within an
115+
Autobuilds run, including building, tagging, running Docker Compose tests, and
116+
running optional bash hook files.
117+
118+
### Steps to migrate
119+
120+
1. Follow the instructions in the [example repository
121+
readme](https://github.com/docker/autobuilds-actions) to configure a CI GitHub
122+
Action workflow in your GitHub repository.
123+
124+
2. The workflows contain comments on what each step does and where changes
125+
should be made. Important changes to make include:
126+
127+
- Set the `DOCKER_REPOSITORY_NAME` environment variable to the full name of your Docker Hub repository
128+
- Set your image tagging policy
129+
- Set the workflow triggers
130+
131+
Links to relevant documentation are provided in the readme and the workflow comments.
132+
133+
3. After you have completed migrating to GitHub Actions, delete the build
134+
configuration from your Docker Hub repository:
135+
136+
1. Navigate to the repository's **Builds** tab.
137+
138+
2. Select **Configure automated builds**.
139+
140+
3. Select **Delete Build Configuration**.
141+
142+
{{< /tab >}}
143+
{{< tab name="Bitbucket Pipelines" >}}
144+
145+
If your source code repository is hosted on Bitbucket, see the [Docker
146+
Autobuilds Bitbucket example
147+
repository](https://bitbucket.org/docker-io/autobuilds-pipeline).
148+
149+
All files except the `bitbucket-pipelines.yml` file are for example purposes only.
150+
151+
The repository's readme details how to migrate from Autobuilds to Bitbucket
152+
Pipelines using the provided example `bitbucket-pipelines.yml` configuration
153+
file.
154+
155+
The pipeline example contains three separate pipelines:
156+
157+
- `branches/main`: Shows how to build, test, and push an image on changes to a specific branch
158+
- `tags/*`: Shows how to build, test, and push an image on tag pushes, including
159+
tagging the image the same as the Git tag
160+
- `pull-requests/*`: Shows how to build and test, but not push, an image from a pull request
161+
162+
### Steps to migrate
163+
164+
1. Follow the instructions in the [example repository
165+
readme](https://bitbucket.org/docker-io/autobuilds-pipeline) to configure
166+
a Bitbucket Pipeline in your Bitbucket repository.
167+
168+
2. Comments in the pipeline configuration explain what each part does and where
169+
changes need to be made. Important changes to make include:
170+
171+
- Set the `DOCKER_REPOSITORY_NAME` environment variable to the full name of
172+
your Docker Hub repository
173+
- Set your image tagging policy (see where the `DOCKER_TAG` variable is set in each pipeline)
174+
- Set the pipeline triggers for branches, tags, and/or pull-requests
175+
176+
Links to relevant documentation are provided in the readme and the workflow comments.
177+
178+
3. After you have completed migrating to Bitbucket Pipelines, delete the Build
179+
configuration from your Docker Hub repository:
180+
181+
1. Navigate to the repository's **Builds** tab.
182+
183+
2. Select **Configure automated builds**.
184+
185+
3. Select **Delete Build Configuration**.
186+
187+
{{< /tab >}}
188+
{{< /tabs >}}

0 commit comments

Comments
 (0)