Skip to content

GitHub Actions and Docker

GitHub Actions is a feature that allows automation and execution of workflows invoved in the development of your software and code. Read more on GitHub Actions at the offical GitHub Docs page.

Actions can also be used to create and manage your Docker Images.

Here you will learn how to can create Actions which build and then push images from GitHub to a Docker Registry of your choice.


Setting up a Git Repository with Actions for Docker

CI/CD Terminology
  • continuous integration builds, tests, and automatically accepts changes to code in a repository
  • continuous delivery delivers code changes to production-ready environments
  • continuous deployment does just that, it deploys changes to the code
  • CI pipeline compiles code, tests it, and makes sure all of your changes work. It should run whenever there is a change (push) to the repository

  • CD pipeline goes one step further and deploys new code into production.

We are focusing on GitHub, but there are other platforms which you can explore for building and pushing containers to registries

These include GitLab Runners

Other types of Continuous Integration are used on code repositories to ensure that code stays functional.

Create a GitHub Repository

Navigate to your GitHub Account and select New;


Creating README, LICENSE, & .gitignore

When you create your new git repository you are asked to create a README, a LICENCE, and a .gitignore file.

Go ahead and create all three of these, as they are useful and fundamental to making your repository reproducible.

README -- we want to use the README to help future-us when we revisit this repository. Make sure to include detailed instructions

LICENSE -- pick a license which is useful for your specific software use case.

.gitignore -- use a file which will keep docker project files isolated

.gitignore example
    # Docker project generated files to ignore
    #  if you want to ignore files created by your editor/tools,
    #  please consider a global .gitignore

In the repository, create two nested folders required for a Docker Actions project:

  • A .github/workflows folder: containing required necessary yml files that build the containers through GitHub;

In the workflows folder, we're going to add a .yml

In the main repository, along with the README and LICENCE file, create another folder called /docker

In the /docker folder we're going to put the Dockerfile file necessary to build the image.

Ensure you can access Docker Hub from any workflows you create:

  1. Add your Docker ID as a secret to GitHub. Navigate to your GitHub repository and click Settings > Secrets > New secret.


2. Create a new secret with the name DOCKER_HUB_USERNAME and your Docker ID as value. 3. On DockerHub, create a new Personal Access Token (PAT). To create a new token, go to Docker Hub Settings and then click New Access Token. Name it, and copy the newly generated PAT.


Name your Docker Hub Access token the same name as your GitHub repository, it will help with keeping track which GitHub repository is related to which Docker image.


  1. On GitHub, return to your repository secrets, and add the PAT as a secret with the name DOCKER_HUB_ACCESS_TOKEN.


Setting up a GitHub Action Workflow

Now that you have connected your GitHub repository with your Docker account, you are ready to add the necessary files to your repo.


In this example, we will use the existing Docker Image Alpine.

1. In your GitHub repository, create a file and name in Dockerfile; In the first line of your Dockerfile paste:

FROM alpine:3.14

2. Click the Actions tab and in the search bar, search for docker. Select the docker image workflow (as shown in the image below)


This will create the `.github/workflows` repository and necessary `yml` file required for the GitHub actions.


3. You will be prompted to the docker-image.yml file; paste the following code, and commit your changes.

name: Docker Image Small Alpine

    branches: [ main ]
    branches: [ main ]



    runs-on: ubuntu-latest

        name: Checkout 
        uses: actions/checkout@v2
        name: Login to Docker Hub
        uses: docker/login-action@v1
          username: ${{ secrets.DOCKER_HUB_USERNAME }}
          password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
        name: Build and push
        uses: docker/build-push-action@v2
          context: .
          file: ./Dockerfile
          push: true
          tags: ${{ secrets.DOCKER_HUB_USERNAME }}/simplewhale
4. Upon committing and pushing your changes, you can check your Workflows under the Actions tab on GitHub.


Github will show you when a workflow is building:
- An orange dot next to your commit count means that the workflow is running;
- A crossed red circle means that your workflow has failed;
- A green check means your workflow ran successfully.


5. Navigate to your Docker Hub to see your GitHub Actions generated Docker image.



Tagging a Pushing an Image

When updating your own Docker Images, you may want to tag the images with a version number.

In this example, we update our Alpine Docker Image to a newer version and adding a package.

Navigate to your Dockerfile and modify it by adding the following lines:

FROM alpine:3.15

LABEL author="<name>" 
LABEL email="<email>"
LABEL date_created="<date>"

RUN apk update && apk upgrade --available
RUN apk add vim fortune

ENV PATH=/usr/games:${PATH}



Save, and navigate to the github action (.github/workflows/docker-image.yml). The last line should be tags, edit the line to reflect the version you would like to add.

tags: ${{ secrets.DOCKER_HUB_USERNAME }}/simplewhale:v0.2


  • To correctoy add a tag, add a colon followed by a version number such as <name of container>:<version number>.
  • If there is no tag, the version pushed will default to latest.
  • Remember to update/change the tag line in future pushes.

Add, commit, push your changes; You will see your Docker Image being built with the added tagged version.


Setting up your own

GitHub Actions Runner

Self-hosted Actions Runner Docs

GitLab Runner