Skip to content

Commit 2c35b5c

Browse files
dvdksndvdksn
committed
guides: docker build github actions primer
Signed-off-by: David Karlsson <[email protected]>
1 parent 548f411 commit 2c35b5c

File tree

2 files changed

+259
-1
lines changed

2 files changed

+259
-1
lines changed

‎content/guides/gha.md‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
---
2+
title: Introduction to GitHub Actions with Docker
3+
linkTitle: GitHub Actions and Docker
4+
summary: |
5+
Learn how to automate image build and push with GitHub Actions.
6+
params:
7+
tags: [devops]
8+
time: 10 minutes
9+
---
10+
11+
This guide provides an introduction to building CI pipelines using Docker and
12+
GitHub Actions. You'll learn how to automate Docker builds, run containerized
13+
tests, and optimize your workflows for enhanced security and efficiency.
14+
15+
You will learn how to use Docker's official GitHub Actions to build your
16+
application as a Docker image and push it to Docker Hub. By the end of the
17+
guide, you'll have a simple, functional GitHub Actions configuration for Docker
18+
builds. Use it as-is, or extend it further to fit your needs.
19+
20+
## Prerequisites
21+
22+
If you want to follow along with the guide, ensure you have the following:
23+
24+
- A Docker account.
25+
- Familiarity with Dockerfiles.
26+
27+
This guide assumes basic knowledge of Docker concepts but provides explanations
28+
for using Docker in GitHub Actions workflows.
29+
30+
## Get the sample app
31+
32+
This guide is project-agnostic and assumes you have an application with a
33+
Dockerfile.
34+
35+
If you need a sample project to follow along, you can use [this sample
36+
application](https://github.com/dvdksn/rpg-name-generator.git), which includes
37+
a Dockerfile for building a containerized version of the app. Alternatively,
38+
use your own GitHub project or create a new repository from the template.
39+
40+
{{% dockerfile.inline %}}
41+
42+
{{ $data := resources.GetRemote "https://raw.githubusercontent.com/dvdksn/rpg-name-generator/refs/heads/main/Dockerfile" }}
43+
44+
```dockerfile {collapse=true}
45+
{{ $data.Content }}
46+
```
47+
48+
{{% /dockerfile.inline %}}
49+
50+
## Configure your GitHub repository
51+
52+
The workflow in this guide pushes the image you build to Docker Hub. To do
53+
that, you must authenticate with your Docker credentials (username and access
54+
token) as part of the GitHub Actions workflow.
55+
56+
For instructions on how to create a Docker access token, see
57+
[Create and manage access tokens](/manuals/security/for-developers/access-tokens.md).
58+
59+
Once you have your Docker credentials ready, add the credentials to your GitHub
60+
repository so you can use them in GitHub Actions:
61+
62+
1. Open your repository's **Settings**.
63+
2. Under **Security**, go to **Secrets and variables > Actions**.
64+
3. Under **Secrets**, create a new repository secret named `DOCKER_PASSWORD`,
65+
containing your Docker access token.
66+
4. Next, under **Variables**, create a `DOCKER_USERNAME` repository variable
67+
containing your Docker Hub username.
68+
69+
## Set up your GitHub Actions workflow
70+
71+
GitHub Actions workflows define a series of steps to automate tasks, such as
72+
building and pushing Docker images, in response to triggers like commits or
73+
pull requests. In this guide, the workflow focuses on automating Docker builds
74+
and testing, ensuring your containerized application works correctly before
75+
publishing it.
76+
77+
Create a file named `docker-ci.yml` in the `.github/workflows/` directory of
78+
your repository. Start with the basic workflow configuration:
79+
80+
```yaml
81+
name: Build and Push Docker Image
82+
83+
on:
84+
push:
85+
branches:
86+
- main
87+
pull_request:
88+
```
89+
90+
This configuration runs the workflow on pushes to the main branch and on pull
91+
requests. By including both triggers, you can ensure that the image builds
92+
correctly for a pull request before it's merged.
93+
94+
## Extract metadata for tags and annotations
95+
96+
For the first step in your workflow, use the `docker/metadata-action` to
97+
generate metadata for your image. This action extracts information about your
98+
Git repository, such as branch names and commit SHAs, and generates image
99+
metadata such as tags and annotations.
100+
101+
Add the following YAML to your workflow file:
102+
103+
```yaml
104+
jobs:
105+
build:
106+
runs-on: ubuntu-latest
107+
steps:
108+
- name: Checkout
109+
uses: actions/checkout@v4
110+
- name: Extract Docker image metadata
111+
id: meta
112+
uses: docker/metadata-action@v5
113+
with:
114+
images: ${{ vars.DOCKER_USERNAME }}/my-image
115+
```
116+
117+
These steps prepare metadata to tag and annotate your images during the build
118+
and push process.
119+
120+
- The **Checkout** step clones the Git repository.
121+
- The **Extract Docker image metadata** step extracts Git metadata and
122+
generates image tags and annotations for the Docker build.
123+
124+
## Authenticate to your registry
125+
126+
Before you build the image, authenticate to your registry to ensure that you
127+
can push your built image to the registry.
128+
129+
To authenticate with Docker Hub, add the following step to your workflow:
130+
131+
```yaml
132+
- name: Log in to Docker Hub
133+
uses: docker/login-action@v3
134+
with:
135+
username: ${{ vars.DOCKER_USERNAME }}
136+
password: ${{ secrets.DOCKER_PASSWORD }}
137+
```
138+
139+
This step uses the Docker credentials [configured in the repository settings](#configure-your-github-repository).
140+
141+
## Build and push the image
142+
143+
Finally, build the final production image and push it to your registry. The
144+
following configuration builds the image and pushes it directly to a registry.
145+
146+
```yaml
147+
- name: Build and push Docker image
148+
uses: docker/build-push-action@v6
149+
with:
150+
push: ${{ github.event_name != 'pull_request' }}
151+
tags: ${{ steps.meta.outputs.tags }}
152+
annotations: ${{ steps.meta.outputs.annotations }}
153+
```
154+
155+
In this configuration:
156+
157+
- `push: ${{ github.event_name != 'pull_request' }}` ensures that images are
158+
only pushed when the event is not a pull request. This way, the workflow
159+
builds and tests images for pull requests but only pushes images for commits
160+
to the main branch.
161+
- `tags` and `annotations` use the outputs from the metadata action to apply
162+
consistent tags and [annotations](/manuals/build/metadata/annotations.md) to
163+
the image automatically.
164+
165+
## Attestations
166+
167+
SBOM (Software Bill of Materials) and provenance attestations improve security
168+
and traceability, ensuring your images meet modern software supply chain
169+
requirements.
170+
171+
With a small amount of additional configuration, you can configure
172+
`docker/build-push-action` to generate Software Bill of Materials (SBOM) and
173+
provenance attestations for the image, at build-time.
174+
175+
To generate this additional metadata, you need to make two changes to your
176+
workflow:
177+
178+
- Before the build step, add a step that uses `docker/setup-buildx-action`.
179+
This action configures your Docker build client with additional capabilities
180+
that the default client doesn't support.
181+
- Then, update the **Build and push Docker image** step to also enable SBOM and
182+
provenance attestations.
183+
184+
Here's the updated snippet:
185+
186+
```yaml
187+
- name: Set up Docker Buildx
188+
uses: docker/setup-buildx-action@v3
189+
190+
- name: Build and push Docker image
191+
uses: docker/build-push-action@v6
192+
with:
193+
push: ${{ github.event_name != 'pull_request' }}
194+
tags: ${{ steps.meta.outputs.tags }}
195+
annotations: ${{ steps.meta.outputs.annotations }}
196+
provenance: true
197+
sbom: true
198+
```
199+
200+
For more details about attestations, refer to
201+
[the documentation](/manuals/build/metadata/attestations/_index.md).
202+
203+
## Conclusion
204+
205+
With all the steps outlined in the previous section, here's the full workflow
206+
configuration:
207+
208+
```yaml
209+
name: Build and Push Docker Image
210+
211+
on:
212+
push:
213+
branches:
214+
- main
215+
pull_request:
216+
217+
jobs:
218+
build:
219+
runs-on: ubuntu-latest
220+
steps:
221+
- name: Checkout
222+
uses: actions/checkout@v4
223+
224+
- name: Extract Docker image metadata
225+
id: meta
226+
uses: docker/metadata-action@v5
227+
with:
228+
images: ${{ vars.DOCKER_USERNAME }}/my-image
229+
230+
- name: Log in to Docker Hub
231+
uses: docker/login-action@v3
232+
with:
233+
username: ${{ vars.DOCKER_USERNAME }}
234+
password: ${{ secrets.DOCKER_PASSWORD }}
235+
236+
- name: Set up Docker Buildx
237+
uses: docker/setup-buildx-action@v3
238+
239+
- name: Build and push Docker image
240+
uses: docker/build-push-action@v6
241+
with:
242+
push: ${{ github.event_name != 'pull_request' }}
243+
tags: ${{ steps.meta.outputs.tags }}
244+
annotations: ${{ steps.meta.outputs.annotations }}
245+
provenance: true
246+
sbom: true
247+
```
248+
249+
This workflow implements best practices for building and pushing Docker images
250+
using GitHub Actions. This configuration can be used as-is or extended with
251+
additional features based on your project's needs, such as
252+
[multi-platform](/manuals/build/building/multi-platform.md).
253+
254+
### Further reading
255+
256+
- Learn more about advanced configurations and examples in the [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) section.
257+
- For more complex build setups, you may want to consider [Bake](/manuals/build/bake/_index.md). (See also the [Mastering Buildx Bake guide](/guides/bake/index.md).)
258+
- Learn about Docker's managed build service, designed for faster, multi-platform builds, see [Docker Build Cloud](/guides/docker-build-cloud/_index.md).

‎content/manuals/build/ci/github-actions/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Introduction to GitHub Actions
2+
title: Docker Build GitHub Actions
33
linkTitle: GitHub Actions
44
description: Docker maintains a set of official GitHub Actions for building Docker images.
55
keywords: ci, github actions, gha, build, introduction, tutorial

0 commit comments

Comments
 (0)