How to Publish a Docker Image Tagged by Release in GitHub Actions

docker/metadata-action turns the pushed git tag into semver image tags (for example 1.2.3, 1.2, latest) that build-push-action then pushes.

On a tag push, run docker/metadata-action with a type=semver tag rule, log in to the registry, and pass its tags output to docker/build-push-action.

Steps

Trigger on push.tags for your version glob.
Run docker/metadata-action with type=semver patterns.
Log in, then run build-push-action with the derived tags.

Workflow

.github/workflows/release.yml

on:
  push:
    tags: ['v*.*.*']
permissions:
  contents: read
  packages: write
jobs:
  image:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ${{ steps.meta.outputs.tags }}

Gotchas

A v prefix on the tag is handled by metadata-action; the image tags drop it.
Grant packages: write for GHCR, or the push fails with a 403.

How to Publish a Docker Image Tagged by Release in GitHub Actions

Steps

Workflow

Gotchas

Related guides