Publishing Container Images to GitHub Container Registry

2024-06-18 4 min read Tutorial

Do you have a container image that you want to share with the world? GitHub Container Registry (GHCR) is a great place to store and share your container images. In this tutorial, we’ll show you how to publish container images to GHCR using GitHub Actions.

Start by creating a new repository on GitHub or cloning an existing one. Then make sure you have a Dockerfile in the root of your repository.

We need to create a GitHub Actions workflow file in the .github/workflows directory of your repository. This file will define the steps to build and publish your container image to GHCR.

Run the following commands to create the workflow file:

mkdir -p .github/workflows
touch .github/workflows/publish.yml

Open the publish.yml file in your favorite text editor and add the following content which is available in the GitHub documentation:

The difference between the original documentation and the code below is this workflow triggers on the main branch and the inclusion of the latest tag for the default branch.

#
name: Create and publish a Docker image

# Configures this workflow to run every time a change is pushed to the branch called `release`.
on:
  push:
    branches: ['main']

# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
    permissions:
      contents: read
      packages: write
      attestations: write
      id-token: write
      # 
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            # set latest tag for default branch
            type=raw,value=latest,enable={{is_default_branch}}            
      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
      - name: Build and push Docker image
        id: push
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
      
      # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see "[AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)." 
      - name: Generate artifact attestation
        uses: actions/attest-build-provenance@v1
        with:
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true

Commit the changes to your repository:

git add .github/workflows/publish.yml
git commit -m "Add publish workflow"
git push

Now, whenever you push changes to the main branch, the workflow will be triggered, building and publishing your container image to GHCR.

The container image will be available as a package under your GitHub profile but it will also be listed as a package in the repository where the workflow is defined. This is linked to your repo via container labels. You can verify this by pulling the container image and running a docker inspect command.

That’s it! You’ve successfully published a container image to GitHub Container Registry using GitHub Actions.

Happy coding!

For more info, check out these resources: