
Publishing Docker images is a common CI/CD task, and the tight integration GitHub Actions has with GitHub repositories makes it a great tool for the job.
Motivation
Automated builds, when combined with tests, are a great tool to increase iteration speed on projects through time savings.
Imagine you maintain a public Docker image of an application that has frequent version changes - every time a new version is released you'll have to spend time building, tagging, testing, and publishing a new version. Now imagine you had a tool to update the application version for you automatically in your Dockerfile, and a CI/CD workflow that would take care of the building, tagging, testing, and publishing of the image - it could maintain itself indefinitely without your intervention.
We'll touch on the second part here, the CI/CD workflow for Docker images.
About GitHub Actions
GitHub Actions left beta about a year ago , and has been growing in popularity as a replacement for other CI/CD services in part to its tight integration with GitHub repositories.
As of writing, the Actions free plan offers unlimited build minutes for public repositories, 2,000 build minutes per month for private repositories, and 20 concurrent jobs - much more than other freemium services.
Setup
For this project you will need a couple things:
- A GitHub repository for your code
- A Docker Hub account to push your image to
Building the image
Let's make a simple hello world Dockerfile:
1FROM alpine:3.13.2
2CMD ["echo", "Hello world!"]
This can be tested with a command such as:
$ docker build --tag helloworld . && docker run helloworld
Hello world!Then we'll create the beginnings of our Actions workflow at .github/workflows/main.yml:
1name: CI/CD
2
3# Run on pushes to any branch
4on: push
5
6jobs:
7 build:
8 name: Docker build
9
10 # Use the Ubuntu virtual environment to run this job in
11 runs-on: ubuntu-latest
12
13 steps:
14 # Checkout the repository files
15 - name: Checkout
16 uses: actions/checkout@v2
17
18 # Build the hello world image
19 - name: Build Docker image
20 run: docker build --tag helloworld .
With this config, GitHub Actions will execute the workflow on every code push, so once these files are committed and pushed, Actions will run docker build and continue to on every subsequent push. The workflow should finish in under 15 seconds, and if we see that succeed in the Actions or Pull Request UI then we know the image built successfully.
Publishing the image
Building the Docker image is great, but that image artifact disappeared when the job finished. In order to save our work we'll want to publish the image - what this post is all about!
First, we'll want to set an image name to publish under. To keep things easier to read, I will collapse some parts of the Dockerfile that haven't changed.
1name: CI/CD
2
3on: push
4
5# Define the image tag
6env:
7 IMAGE_TAG: <username>/helloworld:latest
8
9jobs:
10 build:
11 name: Docker build
12 runs-on: ubuntu-latest
13 steps:
14 - name: Checkout
15 uses: actions/checkout@v2
16
17 - name: Build Docker image
18 # Tag using the image tag above
19 run: docker build --tag "${IMAGE_TAG}" .
Replace <username> with your own Docker Hub username.
To save the output of the build to be used later, we'll save it to the workflow's "artifacts":
1name: CI/CD
2
3on: push
4
5env:
6 IMAGE_TAG: <username>/helloworld:latest
7
8jobs:
9 build:
10 name: Docker build
11 runs-on: ubuntu-latest
12 steps:
13 - name: Checkout
14 uses: actions/checkout@v2
15
16 - name: Build Docker image
17 run: docker build --tag "${IMAGE_TAG}" .
18
19 # Archive and persist the Docker image
20 - name: Save Docker image
21 run: docker save --output image.tar "${IMAGE_TAG}"
22 - name: Upload Docker image
23 uses: actions/upload-artifact@v2
24 with:
25 name: docker-image
26 path: image.tar
27 retention-days: 1
Because the image is very small, even archiving and saving the output should still keep our build time under 15 seconds.
One thing to note is the action actions/upload-artifact@v2 is very slow, I've seen it take more than 8 minutes for an almost 3GB Docker image. That's an extreme case, no sane image should be that large, but it's something to keep in mind.
In order to push images to Docker Hub we'll need to supply GitHub with our credentials. In your GitHub repository's settings there is a page to configure secrets. We'll need a secret named DOCKERHUB_USERNAME with the value of your username, and one named DOCKERHUB_PASS with the value of a personal access token created for GitHub. I would recommend against saving your password in plaintext.
Now we're ready to add a job to log in to Docker Hub and push the image:
1name: CI/CD
2
3on: push
4
5env:
6 IMAGE_TAG: <username>/helloworld:latest
7
8jobs:
9 build:
10 name: Docker build
11 runs-on: ubuntu-latest
12 steps:
13 - name: Checkout
14 uses: actions/checkout@v2
15
16 - name: Build Docker image
17 run: docker build --tag "${IMAGE_TAG}" .
18
19 - name: Save Docker image
20 run: docker save --output image.tar "${IMAGE_TAG}"
21 - name: Upload Docker image
22 uses: actions/upload-artifact@v2
23 with:
24 name: docker-image
25 path: image.tar
26 retention-days: 1
27
28 push:
29 name: Docker push
30 runs-on: ubuntu-latest
31
32 # Build needs to finish first
33 needs: build
34
35 # Only push images from the main branch
36 if: github.ref == 'refs/heads/main'
37
38 steps:
39 # Load and un-archive the Docker image
40 - name: Download Docker image
41 uses: actions/download-artifact@v2
42 with:
43 name: docker-image
44 - name: Load Docker image
45 run: docker load --input image.tar
46
47 # Log in to Docker Hub and push the image
48 - name: Publish Docker image
49 env:
50 DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
51 DOCKERHUB_PASS: ${{ secrets.DOCKERHUB_PASS }}
52 run: |
53 echo "${DOCKERHUB_PASS}" | docker login --username "${DOCKERHUB_USERNAME}" --password-stdin
54 docker push "${IMAGE_TAG}"
Upon pushing that change, GitHub will publish a public image named helloworld with a single tag latest under your Docker Hub account. The whole workflow should take less than 30 seconds.
Bonus: testing the image
I've previously talked about testing Docker images with Container Structure Test, a great tool from Google to test your built docker images - and it's very easy to add to our GitHub Actions workflow.
Testing Docker Images with Container Structure Test
Jul 18, 2020 · 5 min read
Just because a Docker image builds successfully doesn't mean it will perform as expected. Google's container Structure Test tool helps you check images to make sure they're working as intended.
First, make a container-structure-test.yml:
1schemaVersion: 2.0.0
2commandTests:
3 - name: "docker run"
4 # `command` is required, so we'll have it match the Dockerfile
5 command: "echo"
6 args: ["Hello world!"]
7 expectedOutput: ["Hello world!"]
8 excludedError: [".+"]
9 exitCode: 0
This isn't a very valuable test because it replaces all the functionality of the Dockerfile, allowing for the two get out of sync - but it will work well enough to show the Actions config.
To run Container Structure Test in our Actions workflow, add a step just after docker build:
1name: CI/CD
2
3on: push
4
5env:
6 IMAGE_TAG: <username>/helloworld:latest
7
8jobs:
9 build:
10 name: Docker build
11 runs-on: ubuntu-latest
12 steps:
13 - name: Checkout
14 uses: actions/checkout@v2
15
16 - name: Build Docker image
17 run: docker build --tag "${IMAGE_TAG}" .
18
19 # Run Container Structure Test against the built image
20 - name: Test Docker image
21 run: |
22 curl -LO https://storage.googleapis.com/container-structure-test/latest/container-structure-test-linux-amd64 && chmod +x container-structure-test-linux-amd64 && sudo mv container-structure-test-linux-amd64 /usr/local/bin/container-structure-test
23 container-structure-test test --config container-structure-test.yml --image "${IMAGE_TAG}"
24
25 - name: Save Docker image
26 run: docker save --output image.tar "${IMAGE_TAG}"
27 - name: Upload Docker image
28 uses: actions/upload-artifact@v2
29 with:
30 name: docker-image
31 path: image.tar
32 retention-days: 1
33
34 # push: (collapsed)
If Container Structure Test doesn't pass, it will exit with a non-zero exit code, which will fail the step and the entire job.
Bonus: linting the Dockerfile
I've also previously talked about linting Dockerfiles with Hadolint, to both help enforce style guidelines and help catch potential issues. It's also a simple addition to our workflow.
Linting Dockerfiles with Hadolint
Aug 10, 2020 · 3 min read
Linters don't just enforce style guidelines, they also catch potential issues. hadolint (Haskell Dockerfile Linter) is the most popular linter for Dockerfiles, and it's incredibly easy to use.
To run Hadolint, add a step just before docker build:
1name: CI/CD
2
3on: push
4
5env:
6 IMAGE_TAG: <username>/helloworld:latest
7
8jobs:
9 build:
10 name: Docker build
11 runs-on: ubuntu-latest
12 steps:
13 - name: Checkout
14 uses: actions/checkout@v2
15
16 # Lint the Dockerfile
17 - name: Lint Dockerfile
18 run: docker run --rm --interactive hadolint/hadolint < Dockerfile
19
20 - name: Build Docker image
21 run: docker build --tag "${IMAGE_TAG}" .
22
23 - name: Save Docker image
24 run: docker save --output image.tar "${IMAGE_TAG}"
25 - name: Upload Docker image
26 uses: actions/upload-artifact@v2
27 with:
28 name: docker-image
29 path: image.tar
30 retention-days: 1
31
32 # push: (collapsed)
If Hadolint doesn't pass, it will exit with a non-zero exit code, which will fail the step and the entire job.
Other CI/CD tools
If GitHub Actions isn't the right tool for you, check out how to accomplish this same workflow using CircleCI.

Publishing Docker Images with CircleCI
Feb 15, 2021 · 9 min read
Publishing Docker images is a common CI/CD task, and the flexibility CircleCI offers makes it a great tool for the job.


