How to publish a Docker image to a registry from CI

What and why

Shipping containers means building an image in CI and pushing it to a registry that deployment pulls from. Doing this reliably requires secure authentication, consistent tags, and pushing only on the right events. This tutorial builds and publishes an image.

Prerequisites

• A Dockerfile in your repository.
• A container registry account (such as GitHub Container Registry or Docker Hub).
• A CI pipeline you can extend.

Steps

1. Store registry credentials

Add registry credentials as CI secrets, never in the repo. For GitHub Container Registry the built-in GITHUB_TOKEN can push to your org's registry.

2. Log in to the registry

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

Login must run before any push.

3. Set up multi-platform builds

      - uses: docker/setup-buildx-action@v3

Buildx enables build caching and multi-architecture images.

4. Generate image tags

      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/acme/web

This derives tags from the branch, tag, and commit so each image is traceable.

5. Build and push

      - uses: docker/build-push-action@v6
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}

The condition builds on pull requests but pushes only on merges, so untrusted forks cannot publish.

Verification

Merge a change and check the registry: the new image should appear with tags for the branch and commit SHA. Pull it locally with docker pull and run it to confirm it works.

Next Steps

Sign images and generate provenance for supply-chain trust. Add a vulnerability scan before push. Promote the same digest across environments instead of rebuilding per stage.