mirror of
https://github.com/docker/docs.git
synced 2026-11-04 10:01:00 +00:00
Consolidate the GitHub Actions introduction in the build manual (#26488)
Move repository credential setup and a complete build-and-push workflow into the GitHub Actions manual. Skip registry sign-in and publishing for pull requests, and link to specialist examples for testing, metadata, attestations, and multi-platform builds. Remove the standalone guide and redirect `/guides/gha/` to the manual, preserving existing aliases. Validation: scoped rumdl and Vale checks, Hugo build, and rendered workflow YAML, internal links, navigation, catalog removal, and redirects. GitHub Actions execution was not tested. Some retired heading fragments have no destination equivalent; three setup headings retain compatible IDs.
This commit is contained in:
David Karlsson authored and 
GitHub committed
1 parent
a2cc501182
commit
6a5bbded16
2 files changed
+102
-264
No files matched your search
@@ -1,258 +0,0 @@
|
||||
---
|
||||
title: Introduction to GitHub Actions with Docker
|
||||
description: Automate Docker image builds and publishing with GitHub Actions.
|
||||
linkTitle: GitHub Actions and Docker
|
||||
summary: |
|
||||
Learn how to automate image build and push with GitHub Actions.
|
||||
keywords: github actions, ci/cd, docker hub, build and push, automation, workflows
|
||||
params:
|
||||
tags: [cicd]
|
||||
time: 10 minutes
|
||||
---
|
||||
|
||||
This guide provides an introduction to building CI pipelines using Docker and
|
||||
GitHub Actions. You will learn how to use Docker's official GitHub Actions to
|
||||
build your application as a Docker image and push it to Docker Hub. By the end
|
||||
of the guide, you'll have a simple, functional GitHub Actions configuration for
|
||||
Docker builds. Use it as-is, or extend it further to fit your needs.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
If you want to follow along with the guide, ensure you have the following:
|
||||
|
||||
- A verified Docker account.
|
||||
- Familiarity with Dockerfiles.
|
||||
|
||||
This guide assumes basic knowledge of Docker concepts but provides explanations
|
||||
for using Docker in GitHub Actions workflows.
|
||||
|
||||
## Get the sample app
|
||||
|
||||
This guide is project-agnostic and assumes you have an application with a
|
||||
Dockerfile.
|
||||
|
||||
If you need a sample project to follow along, you can use [this sample
|
||||
application](https://github.com/dvdksn/rpg-name-generator.git), which includes
|
||||
a Dockerfile for building a containerized version of the app. Alternatively,
|
||||
use your own GitHub project or create a new repository from the template.
|
||||
|
||||
{{% dockerfile.inline %}}
|
||||
|
||||
{{ $data := resources.GetRemote "https://raw.githubusercontent.com/dvdksn/rpg-name-generator/refs/heads/main/Dockerfile" }}
|
||||
|
||||
```dockerfile {collapse=true}
|
||||
{{ $data.Content }}
|
||||
```
|
||||
|
||||
{{% /dockerfile.inline %}}
|
||||
|
||||
## Configure your GitHub repository
|
||||
|
||||
The workflow in this guide pushes the image you build to Docker Hub. To do
|
||||
that, you must authenticate with your Docker credentials (username and access
|
||||
token) as part of the GitHub Actions workflow.
|
||||
|
||||
For instructions on how to create a Docker access token, see
|
||||
[Create and manage access tokens](/manuals/security/access-tokens/personal-access-tokens.md).
|
||||
|
||||
Once you have your Docker credentials ready, add the credentials to your GitHub
|
||||
repository so you can use them in GitHub Actions:
|
||||
|
||||
1. Open your repository's **Settings**.
|
||||
2. Under **Security**, go to **Secrets and variables > Actions**.
|
||||
3. Under **Secrets**, create a new repository secret named `DOCKER_PASSWORD`,
|
||||
containing your Docker access token.
|
||||
4. Next, under **Variables**, create a `DOCKER_USERNAME` repository variable
|
||||
containing your Docker Hub username.
|
||||
|
||||
## Set up your GitHub Actions workflow
|
||||
|
||||
GitHub Actions workflows define a series of steps to automate tasks, such as
|
||||
building and pushing Docker images, in response to triggers like commits or
|
||||
pull requests. In this guide, the workflow focuses on automating Docker builds
|
||||
and testing, ensuring your containerized application works correctly before
|
||||
publishing it.
|
||||
|
||||
Create a file named `docker-ci.yml` in the `.github/workflows/` directory of
|
||||
your repository. Start with the basic workflow configuration:
|
||||
|
||||
```yaml
|
||||
name: Build and Push Docker Image
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
pull_request:
|
||||
```
|
||||
|
||||
This configuration runs the workflow on pushes to the main branch and on pull
|
||||
requests. By including both triggers, you can ensure that the image builds
|
||||
correctly for a pull request before it's merged.
|
||||
|
||||
## Extract metadata for tags and annotations
|
||||
|
||||
For the first step in your workflow, use the `docker/metadata-action` to
|
||||
generate metadata for your image. This action extracts information about your
|
||||
Git repository, such as branch names and commit SHAs, and generates image
|
||||
metadata such as tags and annotations.
|
||||
|
||||
Add the following YAML to your workflow file:
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@{{% param "checkout_action_version" %}}
|
||||
- name: Extract Docker image metadata
|
||||
id: meta
|
||||
uses: docker/metadata-action@{{% param "metadata_action_version" %}}
|
||||
with:
|
||||
images: ${{ vars.DOCKER_USERNAME }}/my-image
|
||||
```
|
||||
|
||||
These steps prepare metadata to tag and annotate your images during the build
|
||||
and push process.
|
||||
|
||||
- The **Checkout** step clones the Git repository.
|
||||
- The **Extract Docker image metadata** step extracts Git metadata and
|
||||
generates image tags and annotations for the Docker build.
|
||||
|
||||
## Authenticate to your registry
|
||||
|
||||
Before you build the image, authenticate to your registry to ensure that you
|
||||
can push your built image to the registry.
|
||||
|
||||
To authenticate with Docker Hub, add the following step to your workflow:
|
||||
|
||||
```yaml
|
||||
- name: Log in to Docker Hub
|
||||
uses: docker/login-action@{{% param "login_action_version" %}}
|
||||
with:
|
||||
username: ${{ vars.DOCKER_USERNAME }}
|
||||
password: ${{ secrets.DOCKER_PASSWORD }}
|
||||
```
|
||||
|
||||
This step uses the Docker credentials [configured in the repository settings](#configure-your-github-repository).
|
||||
|
||||
## Build and push the image
|
||||
|
||||
Finally, build the final production image and push it to your registry. The
|
||||
following configuration builds the image and pushes it directly to a registry.
|
||||
|
||||
```yaml
|
||||
- name: Build and push Docker image
|
||||
uses: docker/build-push-action@{{% param "build_push_action_version" %}}
|
||||
with:
|
||||
push: ${{ github.event_name != 'pull_request' }}
|
||||
tags: ${{ steps.meta.outputs.tags }}
|
||||
annotations: ${{ steps.meta.outputs.annotations }}
|
||||
```
|
||||
|
||||
In this configuration:
|
||||
|
||||
- `push: ${{ github.event_name != 'pull_request' }}` ensures that images are
|
||||
only pushed when the event is not a pull request. This way, the workflow
|
||||
builds and tests images for pull requests but only pushes images for commits
|
||||
to the main branch.
|
||||
- `tags` and `annotations` use the outputs from the metadata action to apply
|
||||
consistent tags and [annotations](/manuals/build/metadata/annotations.md) to
|
||||
the image automatically.
|
||||
|
||||
## Attestations
|
||||
|
||||
SBOM (Software Bill of Materials) and provenance attestations improve security
|
||||
and traceability, ensuring your images meet modern software supply chain
|
||||
requirements.
|
||||
|
||||
With a small amount of additional configuration, you can configure
|
||||
`docker/build-push-action` to generate Software Bill of Materials (SBOM) and
|
||||
provenance attestations for the image, at build-time.
|
||||
|
||||
To generate this additional metadata, you need to make two changes to your
|
||||
workflow:
|
||||
|
||||
- Before the build step, add a step that uses `docker/setup-buildx-action`.
|
||||
This action configures your Docker build client with additional capabilities
|
||||
that the default client doesn't support.
|
||||
- Then, update the **Build and push Docker image** step to also enable SBOM and
|
||||
provenance attestations.
|
||||
|
||||
Here's the updated snippet:
|
||||
|
||||
```yaml
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
|
||||
|
||||
- name: Build and push Docker image
|
||||
uses: docker/build-push-action@{{% param "build_push_action_version" %}}
|
||||
with:
|
||||
push: ${{ github.event_name != 'pull_request' }}
|
||||
tags: ${{ steps.meta.outputs.tags }}
|
||||
annotations: ${{ steps.meta.outputs.annotations }}
|
||||
provenance: true
|
||||
sbom: true
|
||||
```
|
||||
|
||||
For more details about attestations, refer to
|
||||
[the documentation](/manuals/build/metadata/attestations/_index.md).
|
||||
|
||||
## Conclusion
|
||||
|
||||
With all the steps outlined in the previous section, here's the full workflow
|
||||
configuration:
|
||||
|
||||
```yaml
|
||||
name: Build and Push Docker Image
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@{{% param "checkout_action_version" %}}
|
||||
|
||||
- name: Extract Docker image metadata
|
||||
id: meta
|
||||
uses: docker/metadata-action@{{% param "metadata_action_version" %}}
|
||||
with:
|
||||
images: ${{ vars.DOCKER_USERNAME }}/my-image
|
||||
|
||||
- name: Log in to Docker Hub
|
||||
uses: docker/login-action@{{% param "login_action_version" %}}
|
||||
with:
|
||||
username: ${{ vars.DOCKER_USERNAME }}
|
||||
password: ${{ secrets.DOCKER_PASSWORD }}
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
|
||||
|
||||
- name: Build and push Docker image
|
||||
uses: docker/build-push-action@{{% param "build_push_action_version" %}}
|
||||
with:
|
||||
push: ${{ github.event_name != 'pull_request' }}
|
||||
tags: ${{ steps.meta.outputs.tags }}
|
||||
annotations: ${{ steps.meta.outputs.annotations }}
|
||||
provenance: true
|
||||
sbom: true
|
||||
```
|
||||
|
||||
This workflow implements best practices for building and pushing Docker images
|
||||
using GitHub Actions. This configuration can be used as-is or extended with
|
||||
additional features based on your project's needs, such as
|
||||
[multi-platform](/manuals/build/building/multi-platform.md).
|
||||
|
||||
### Further reading
|
||||
|
||||
- Learn more about advanced configurations and examples in the [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) section.
|
||||
- Use [Bake targets](/manuals/build/bake/targets.md) to group builds, run checks, and export artifacts.
|
||||
|
||||
- Learn about Docker's managed build service, designed for faster, multi-platform builds, see [Docker Build Cloud](/manuals/build-cloud/_index.md).
|
||||
@@ -4,6 +4,7 @@ linkTitle: GitHub Actions
|
||||
description: Docker maintains a set of official GitHub Actions for building Docker images.
|
||||
keywords: ci, github actions, gha, build, introduction, tutorial
|
||||
aliases:
|
||||
- /guides/gha/
|
||||
- /ci-cd/github-actions/
|
||||
- /build/ci/github-actions/examples/
|
||||
---
|
||||
@@ -39,15 +40,110 @@ The following GitHub Actions are available:
|
||||
Using Docker's actions provides an easy-to-use interface, while still allowing
|
||||
flexibility for customizing build parameters.
|
||||
|
||||
> [!NOTE]
|
||||
> For an alternative to configuring individual actions, see
|
||||
> [Docker GitHub Builder](/manuals/build/ci/github-actions/github-builder/_index.md).
|
||||
> It provides Docker-maintained reusable workflows for building images and artifacts
|
||||
> with BuildKit.
|
||||
|
||||
## Get started
|
||||
|
||||
Build an image from your GitHub repository and push it to Docker Hub with the
|
||||
following workflow.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- A GitHub repository with your application and a `Dockerfile` at its root.
|
||||
- A Docker Hub account and a
|
||||
[personal access token](/manuals/security/access-tokens/personal-access-tokens.md)
|
||||
with permission to push images.
|
||||
|
||||
### Configure your GitHub repository
|
||||
|
||||
Add your Docker Hub credentials to your GitHub repository:
|
||||
|
||||
1. Open your repository's **Settings**.
|
||||
2. Under **Security**, go to **Secrets and variables > Actions**.
|
||||
3. Under **Secrets**, create a repository secret named `DOCKERHUB_TOKEN`
|
||||
containing your Docker access token.
|
||||
4. Under **Variables**, create a repository variable named `DOCKERHUB_USERNAME`
|
||||
containing your Docker Hub username.
|
||||
|
||||
### Set up your GitHub Actions workflow
|
||||
|
||||
Create `.github/workflows/docker-ci.yml` in your repository with the following
|
||||
contents. Replace `my-image` with the name of your Docker Hub repository, and
|
||||
change `main` if your default branch has a different name.
|
||||
|
||||
```yaml
|
||||
name: Build and push Docker image
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
pull_request:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Extract Docker image metadata
|
||||
id: meta
|
||||
uses: docker/metadata-action@{{% param "metadata_action_version" %}}
|
||||
with:
|
||||
images: ${{ vars.DOCKERHUB_USERNAME }}/my-image
|
||||
|
||||
- name: Sign in to Docker Hub
|
||||
if: github.event_name != 'pull_request'
|
||||
uses: docker/login-action@{{% param "login_action_version" %}}
|
||||
with:
|
||||
username: ${{ vars.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
|
||||
|
||||
- name: Build and push Docker image
|
||||
uses: docker/build-push-action@{{% param "build_push_action_version" %}}
|
||||
with:
|
||||
push: ${{ github.event_name != 'pull_request' }}
|
||||
tags: ${{ steps.meta.outputs.tags }}
|
||||
labels: ${{ steps.meta.outputs.labels }}
|
||||
annotations: ${{ steps.meta.outputs.annotations }}
|
||||
```
|
||||
|
||||
Commit the workflow file and push it to your default branch to run it. The
|
||||
workflow also runs on pull requests. Pull-request builds skip signing in to
|
||||
Docker Hub and pushing the image, so they don't require registry secrets,
|
||||
including for pull requests from forks.
|
||||
|
||||
The build action uses Git context by default: BuildKit fetches your repository
|
||||
directly at the Git reference for the event that triggered the workflow, so no
|
||||
checkout step is needed. Changes to files made by earlier workflow steps are
|
||||
ignored because the build uses files from Git.
|
||||
|
||||
The metadata action generates tags, labels, and
|
||||
annotations from the GitHub event and passes them to the build step. For
|
||||
example, a push to `main` publishes `DOCKERHUB_USERNAME/my-image:main`.
|
||||
See [Manage tags and labels](/manuals/build/ci/github-actions/manage-tags-labels.md)
|
||||
and [Annotations](/manuals/build/ci/github-actions/annotations.md) to customize
|
||||
this metadata.
|
||||
|
||||
This workflow builds images but doesn't run application tests. To add tests,
|
||||
see [Test before push](/manuals/build/ci/github-actions/test-before-push.md).
|
||||
For additional build options, see
|
||||
[Multi-platform images](/manuals/build/ci/github-actions/multi-platform.md) and
|
||||
[SBOM and provenance attestations](/manuals/build/ci/github-actions/attestations.md),
|
||||
which covers default provenance and how to add SBOM attestations when pushing
|
||||
to a registry.
|
||||
|
||||
## Examples
|
||||
|
||||
If you're looking for examples on how to use the Docker GitHub Actions,
|
||||
refer to the following sections:
|
||||
|
||||
{{% sectionlinks %}}
|
||||
|
||||
## Get started with GitHub Actions
|
||||
|
||||
The [Introduction to GitHub Actions with Docker](/guides/gha.md) guide walks
|
||||
you through the process of setting up and using Docker GitHub Actions for
|
||||
building Docker images, and pushing images to Docker Hub.
|
||||
Reference in new issue
Block a user