Example use of GitHub Actions for building, testing, and releasing a Docker container

This repo is an example of using GitHub Actions for CI/CD using the following technologies:

• Docker
• semantic-release
• Docker Hub

About The Container Image Created

The container image created in this repo is just for demonstrations purposes and serves no other use. It is based on the ubuntu:22.04 image and simply installs nano. Also it copies test_content.txt into the image and inserts some data into the file; this is just for testing purposes and is used in the build and test workflow.

Branch Setup

There are two primary branches in this repo main and next. The main branch is the stable release branch and the next branch is the prerelease branch. Emergency fixes and sometime small features can be PR merged into main, but all other features should be PR merged into next. The next branch is merged into main when a new stable release is ready.

Both branches are protected with branch rules that prevent direct pushes and require PRs to add new commits to those branches.

Note - Due to these limitations semantic-release cannot push the new release commit to the main or next branches. To get around this limitation we will introduce a GH_TOKEN_SEMANTIC_RELEASE secret that contains a GitHub Personal Access Token with the repo scope. This token will be used by semantic-release to push the new release commit to the main or next branch. This should only be done in an environment where you can trust all developers/contributors.

See here for details about the workaround used: https://github.com/semantic-release/git/issues/196#issuecomment-702839100.\ See here for how to approach it using a GitHub App: semantic-release/github#175 (comment)

Releases

Releases on main will be tagged with a release semver(example 1.0.0), those on next will have a prerelease semver tag(example 1.0.0-next.1). These tags are used in both the GitHub Release and DockerHub Release. The newest release on main will be tagged as latest on DockerHub.

Workflow

1. On PR request open, reopened, and synchronize events

   • See build-and-test.yml
   • Build and test the docker image
     • All these build/tests jobs must pass before a PR can be merged

2. On push to main or next branches

   • Since these branches are protected, this will only happen when a PR is merged
   • See release.yml
   • Performs:
     • Create GitHub Release via semantic-release
     • Push new Docker images to DockerHub
     • Update description on DockerHub

Local Execution

All contained GitHub Actions workflows are designed for local execution using nektos/act.

See ./test-ci/README.md for details on how to use and test these workflows locally.

DockerHub

Go here to see the test docker container built by this CI/CD example: https://hub.docker.com/repository/docker/johnnyknighten/example-github-actions-for-container-release.

Contribute

If you have any questions, comments, or suggestions please feel free to open an issue or PR. I don't plan on spending too much effort on this repo, it was mainly made as a experimenting repo for myself when I was switching from Gitlab CI/CD to GitHub Actions. I decided to make this a public repo so others could have a good reference and starting point for their own GitHub Actions CI/CD setup. Regardless I will try to respond to any issues or PRs in a timely manner and ensure the repo is still up to date as GitHub Actions is updated.