diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 1af8e5b489e5..52c5c7e8a1ed 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -261,6 +261,7 @@ Zsh [Pp]roxied [Pp]roxying [pP]yright +[Rr]eadme [Rr]eal-time [Rr]egex(es)? [Rr]untimes? diff --git a/content/manuals/docker-hub/repos/manage/builds/images/autobuild-example.png b/content/manuals/docker-hub/repos/manage/builds/images/autobuild-example.png new file mode 100644 index 000000000000..e1ee9af139b1 Binary files /dev/null and b/content/manuals/docker-hub/repos/manage/builds/images/autobuild-example.png differ diff --git a/content/manuals/docker-hub/repos/manage/builds/migrate.md b/content/manuals/docker-hub/repos/manage/builds/migrate.md new file mode 100644 index 000000000000..69bdc1b85c2c --- /dev/null +++ b/content/manuals/docker-hub/repos/manage/builds/migrate.md @@ -0,0 +1,187 @@ +--- +description: Migrate from Autobuilds to CI/CD workflows +keywords: automated builds, autobuilds, migration, github actions, bitbucket pipelines +title: Migrate from Autobuilds +linkTitle: Migrate +weight: 80 +--- + +This guide explains how to migrate your Docker Hub Autobuilds setup to +Continuous Integration (CI) workflows, focusing on GitHub Actions and Bitbucket +Pipelines as these are the built-in CI services for the two version control +services supported via Autobuilds. + +## Step 1: Create access tokens + +To grant your CI workflows the ability to pull and push images to and from +Docker Hub, you first need to create access tokens: + +- For a personal repository: Create a [Personal + AccessToken](../../../../security/access-tokens.md) with **Read & Write** + permissions. + +- For an organization repository: Create an [Organization Access + Token](../../../../enterprise/security/access-tokens.md) with the following + permissions: + - **Read public repositories** + - **Image Pull** on any private repositories that the build needs to pull from + - **Image Push** on the repository that the built image will be pushed to + +The same token can be used for all CI workflows under the account's namespace +provided it has adequate permissions to all relevant Docker Hub repositories. + +Make sure to save the generated token in a safe location for use when setting up +the CI workflows. + +## Step 2: Extract your Autobuilds configuration + +For each Docker Hub repository currently configured to use Autobuilds, you need +to extract its configuration to set up your CI workflows to duplicate the +existing functionality. The only way to extract the configuration is via the +Docker Hub web interface. + +1. Sign in to [Docker Hub](https://hub.docker.com). + +2. Navigate to your repository by going to **My Hub** > ***Your namespace*** > + **Repositories** > ***Your Repository***. + +3. Go to the **Builds** tab and select **Configure automated builds**. + + If there is no existing build configuration, then this repository is not + configured for Autobuilds. + +4. Note the following configuration details: + + - **Source Repository**: The GitHub or Bitbucket repository. The organization + is the namespace and the repository is the repository name. This is where + you need to add your workflow. + + - **Autotest**: If Autotest is enabled for Pull Requests (either internal + only or internal and external), then extra steps are needed in your + workflow to run the Autotest step. + + - **Repository Links**: Not supported and can be ignored. If chain builds are + required, see the documentation for your CI service on how to chain builds + together. + + - **Build Rules**: Specify the triggers, tags, and paths of your builds. + Ignore any entry where **Autobuild** is toggled off. + + - **Build Environment Variables**: User-defined variables injected as + environment variables into your build. You need to add these to your + workflow. If the environment variables are secret, add them as secrets in + the CI service and change your build instructions to read the data from the + secrets. See your CI service documentation on how to handle secrets. + +### Example configuration + +The following image shows an example Autobuilds configuration. + +![Example Autobuilds configuration](./images/autobuild-example.png) + +Based on the pictured example, you would note the following items for this +Autobuilds configuration: + +- Source code repository: GitHub repository `docker/docker-rust-hello` +- Autotest: Disabled +- Build rule 1: Build and push the image with tag `latest` when a new commit to + the `main` branch is detected. The Dockerfile is at `./Dockerfile` and the + build context is the root of the cloned code. +- Build rule 2: Build and push the image with tag `v{\1}` when a new commit + to a tag matching the regex `^v([0-9.]+)$` is detected. The Dockerfile is at + `./Dockerfile` and the build context is the root of the cloned code. +- Environment variable: Key `ENV_KEY` with value `ENV_VALUE` + +## Step 3: Migrate to your CI/CD platform + +Select the tab that matches your source code repository hosting platform. + +{{< tabs >}} +{{< tab name="GitHub Actions" >}} + +If your source code repository is hosted on GitHub, see the [Docker +test-autobuilds example repository](https://github.com/docker/test-autobuilds). + +All files except those under the `.github/workflows` directory are for example +purposes only. + +The repository's readme details how to migrate from Autobuilds to GitHub Actions +using one of the two provided workflows: + +- The `simple-build` workflow builds and pushes a Docker image to your Docker + Hub repository. +- The `full-autobuilds` workflow contains all the steps commonly used within an + Autobuilds run, including building, tagging, running Docker Compose tests, and + running optional bash hook files. + +### Steps to migrate + +1. Follow the instructions in the [example repository + readme](https://github.com/docker/test-autobuilds) to configure a CI GitHub + Action workflow in your GitHub repository. + +2. The workflows contain comments on what each step does and where changes + should be made. Important changes to make include: + + - Set the `DOCKER_REPOSITORY_NAME` environment variable to the full name of your Docker Hub repository + - Set your image tagging policy + - Set the workflow triggers + + Links to relevant documentation are provided in the readme and the workflow comments. + +3. After you have completed migrating to GitHub Actions, delete the build + configuration from your Docker Hub repository: + + 1. Navigate to the repository's **Builds** tab. + + 2. Select **Configure automated builds**. + + 3. Select **Delete Build Configuration**. + +{{< /tab >}} +{{< tab name="Bitbucket Pipelines" >}} + +If your source code repository is hosted on Bitbucket, see the [Docker +test-autobuilds-bitbucket example +repository](https://bitbucket.org/docker/test-autobuilds-bitbucket). + +All files except the `bitbucket-pipelines.yml` file are for example purposes only. + +The repository's readme details how to migrate from Autobuilds to Bitbucket +Pipelines using the provided example `bitbucket-pipelines.yml` configuration +file. + +The pipeline example contains three separate pipelines: + +- `branches/main`: Shows how to build, test, and push an image on changes to a specific branch +- `tags/*`: Shows how to build, test, and push an image on tag pushes, including + tagging the image the same as the Git tag +- `pull-requests/*`: Shows how to build and test, but not push, an image from a pull request + +### Steps to migrate + +1. Follow the instructions in the [example repository + readme](https://bitbucket.org/docker/test-autobuilds-bitbucket) to configure + a Bitbucket Pipeline in your Bitbucket repository. + +2. Comments in the pipeline configuration explain what each part does and where + changes need to be made. Important changes to make include: + + - Set the `DOCKER_REPOSITORY_NAME` environment variable to the full name of + your Docker Hub repository + - Set your image tagging policy (see where the `DOCKER_TAG` variable is set in each pipeline) + - Set the pipeline triggers for branches, tags, and/or pull-requests + + Links to relevant documentation are provided in the readme and the workflow comments. + +3. After you have completed migrating to Bitbucket Pipelines, delete the Build + configuration from your Docker Hub repository: + + 1. Navigate to the repository's **Builds** tab. + + 2. Select **Configure automated builds**. + + 3. Select **Delete Build Configuration**. + +{{< /tab >}} +{{< /tabs >}}