Creating a container image

You can use this workflow step to create a new container image, this mostly relies on the docker/build-push-action, but sets up the environment for easy mutli-arch builds with buildx and qemu. It also logs in to the GitHub container registry allowing you to upload an image right away. To use it, add a job to your GitHub workflow calling this workflow:

# ...

jobs:

  # ...

  docker:
    runs-on: ubuntu-latest
    steps:
      # ...

      - name: Build container image
        uses: tweedegolf/build-container-image@main
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          push: ${{ github.ref == 'refs/heads/main' }}
          platforms: "linux/amd64,linux/arm64"
          tags: ghcr.io/tweedegolf/example:latest

      # ...

  # ...

Workflow inputs

This workflow has several parameters that allow customizing the behavior:

Option	Required	Default
`token`	yes
GitHub token for logging into the ghcr container registry
`tags`	yes
List of image tags (newline separated) for the resulting container image
`push`	no	`false`
If true, the image will be pushed to the registry
`platforms`	no	`""`
Comma separated list of platforms to build the image for, i.e. `linux/amd64,linux/arm64`. If left empty, will only build for the native platform.
`context`	no	`.`
Context directory for the container image build
`build-args`	no	`""`
List of build arguments (newline separated) to be inserted in the container image build
`file`	no	`Dockerfile`
Name of the dockerfile to build
`no-cache`	no	`true`
Set to false to enable caching of docker layers
`pull`	no	`true`
Pull base images from the registry when not available locally

Example usage

Below, you will find a working example where we either just build (and not push) a container image on a pull request, and we fully build and push a container on the main branch, these two require separate permissions. We'll also add a build matrix to allow multiple images to be generated:

.github/workflows/docker.yml

name: Docker

on:
  workflow_call:

jobs:
  docker:
    strategy:
      matrix:
        include:
          - version: trixie
            latest: false
            alt: testing
          - version: bookworm
            latest: true
            alt: stable
          - version: bullseye
            latest: false
            alt: oldstable
    steps:
      - uses: actions/checkout@v4
      - name: Build container image
        uses: tweedegolf/build-container-image@main
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          push: ${{ github.ref == 'refs/heads/main' }}
          platforms: "linux/amd64,linux/arm64"
          build-args: |
            DEBIAN_VERSION=${{matrix.version}}
          tags: |
            ghcr.io/tweedegolf/debian:${{matrix.version}}
            ghcr.io/tweedegolf/debian:${{matrix.alt}}
            ${{ matrix.latest && 'ghcr.io/tweedegolf/debian:latest' || '' }}

This file will be re-used by the two workflows below. As such we only trigger it on workflow_call. Note how we use a matrix to build multiple images. Of course for this workflow to run we'll also need a Dockerfile to be built, but that has been omitted in this example.

.github/workflows/build-push.yml

name: Build and push

permissions:
  contents: read
  packages: write

on:
  push:
    branches:
      - main
  schedule:
    - cron: '30 2 * * SUN'

jobs:
  build-and-push:
    uses: ./.github/workflows/docker.yml

This build and push workflow for the main branch also runs on a schedule every week to keep the image up to date. Note how we require package write permission in this workflow.

.github/workflows/check.yml

name: Checks

permissions:
  contents: read

on:
  pull_request:

jobs:
  build:
    uses: ./.github/workflows/docker.yml
    secrets: inherit

The checks workflow will just need read permissions for the repository with no write permissions required. We only run it for a pull request.