How to Tag a Docker Image by Git SHA and Semver in CI

docker/metadata-action derives a consistent set of tags and OCI labels from the git context for each build.

Run docker/metadata-action with tags: rules (sha, semver, branch), then pass its tags and labels outputs to build-push-action. You get reproducible, traceable tags without hand-writing them.

Steps

• Add docker/metadata-action with the image name and tag rules.
• Use type=sha, type=semver, and type=ref patterns for the tags you want.
• Wire steps.meta.outputs.tags and outputs.labels into the build step.

Workflow

- id: meta
  uses: docker/metadata-action@v5
  with:
    images: ghcr.io/${{ github.repository }}
    tags: |
      type=sha
      type=ref,event=branch
      type=semver,pattern={{version}}
- uses: docker/build-push-action@v6
  with:
    push: true
    tags: ${{ steps.meta.outputs.tags }}
    labels: ${{ steps.meta.outputs.labels }}

Gotchas

• type=semver tags emit only on tag pushes; on branch pushes those entries are skipped.
• By default type=sha uses a 7-char short SHA; add format=long for the full hash.

Related guides