How do I set up GitHub Actions to automatically create and publish Docker images to GHCR on new tags?

[Itskinggy]

🏷️ Discussion Type

Question

💬 Feature/Topic Area

Code Search and Navigation

Body

I'm trying to containerize my Python app and push images to GitHub Container Registry (GHCR) via Actions, but I'm stuck on authentication and tagging. What's the minimal workflow YAML for building on push tags (e.g., v1.0.0), tagging as owner/repo:tag, and using GITHUB_TOKEN? Any gotchas with multi-platform builds or repo permissions?

[NotDizzyButFizzy]

To publish Docker images to GitHub Container Registry (GHCR) automatically on new tags, create a workflow in .github/workflows/docker-publish.yml that triggers on push: tags: ['v*']. Use GITHUB_TOKEN for authentication by adding permissions: { packages: write, contents: read } to the job, then log in with docker/login-action (registry: ghcr.io, username: ${{ github.actor }}, password: ${{ secrets.GITHUB_TOKEN }}). Finally, use docker/build-push-action to build from your Dockerfile context, tagging as ghcr.io/${{ github.repository }}:${{ github.ref_name }} and optionally :latest with push: true. Enable "Inherit access from repository" in repo settings > Packages, and test by pushing a v1.0.0 tag multi-platform builds work by adding platforms: linux/amd64,linux/arm64

[vishvashah07]

To automate the process of building and publishing Docker images to the GitHub Container Registry (GHCR), you can use a GitHub Actions workflow triggered by tags. This is the standard way to handle versioned releases.

Prerequisites
A Dockerfile in the root of your repository.

Write permissions for packages (enabled by default for the GITHUB_TOKEN in most repositories).

The Workflow Configuration
Create a file at .github/workflows/docker-publish.yml and paste the following configuration. This uses official GitHub-maintained actions for maximum security and reliability.

YAML
name: Create and publish a Docker image

on:
push:
tags:
- 'v*' # Triggers on any tag starting with 'v' (e.g., v1.0.1)

env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}

jobs:
build-and-push-image:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write

steps:
  - name: Checkout repository
    uses: actions/checkout@v4

  - name: Log in to the Container registry
    uses: docker/login-action@v3
    with:
      registry: ${{ env.REGISTRY }}
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}

  - name: Extract metadata (tags, labels) for Docker
    id: meta
    uses: docker/metadata-action@v5
    with:
      images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
      tags: |
        type=semver,pattern={{version}}
        type=sha

  - name: Build and push Docker image
    uses: docker/build-push-action@v5
    with:
      context: .
      push: true
      tags: ${{ id.meta.outputs.tags }}
      labels: ${{ id.meta.outputs.labels }}

Key Components Explained
Trigger (on: push: tags): The workflow only runs when you push a tag like v1.0.0. It won't trigger on regular code pushes to main, saving you build minutes.

Permissions: The packages: write permission is crucial. It allows the GITHUB_TOKEN (automatically generated for the job) to upload the image to your repository's registry.

Docker Metadata Action: This is a "quality of life" step. It automatically generates tags for your image. If you push tag v1.2.3, it creates an image tagged ghcr.io/username/repo:1.2.3 and adds a unique SHA tag.

Security: Using ${{ secrets.GITHUB_TOKEN }} ensures you don't have to manually create or manage Personal Access Tokens (PATs) for internal registry access.

How to trigger it
Once the file is committed to your main branch, run these commands in your terminal:

Bash
git tag v1.0.0
git push origin v1.0.0
The "Actions" tab in your GitHub repository will show the build progress. Once finished, the image will appear under the Packages section of your profile or repository.

[itxashancode]

Here’s a minimal, production-ready workflow that builds and pushes Docker images to GHCR on new tags, using GITHUB_TOKEN and supporting multi-platform builds:

name: Publish to GHCR

on:
  push:
    tags:
      - 'v*'  # Triggers on tags