Build & Publish Docker Image to GHCR

A GitHub composite action that builds a Docker image and publishes it to GitHub Container Registry (GHCR) with sensible tags, labels, caching, and multi‑arch support.

---

What it does

This action:

• Computes an image name (defaults to the repo name, lowercased) and optional name_suffix.
• Sets up QEMU and Buildx for multi‑architecture builds (linux/amd64, linux/arm64).
• Logs in to ghcr.io using the GITHUB_TOKEN.
• Generates tags & labels via docker/metadata-action (latest on default branch, branch/tag refs, short SHA, plus any extra_tags).
• Builds with docker/build-push-action and GitHub Actions cache.
• Pushes when push: true (e.g., on main or tags) and skips pushing on PRs if configured.

Images are published to ghcr.io/agile-software-engineering-25/<image> with the generated tags.

---

Usage

Quick start

name: Build & (maybe) Publish

on:
  push:
    branches: [ "main" ]        
    tags:     [ "v*", "release-*" ]

permissions:
  contents: read
  packages: write

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Build (and conditionally push)
        uses: Agile-Software-Engineering-25/build-and-publish-image@v1
        with:
          # optional — defaults shown:
          # image_name: ""                 # defaults to repo name (lowercased)
          # context: "."
          # file: "Dockerfile"
          # name_suffix: ""                # e.g. "-frontend" or "-backend"
          # platforms: "linux/amd64,linux/arm64"
          # extra_tags: ""                 # e.g. "type=raw,value=prod"
          # build_args: |                  # newline separated KEY=VALUE
          #   BASE_PATH=/team/app/my-app/
          push: ${{ github.event_name != 'pull_request' }}

Local testing (inside this repo)

- name: Build (and conditionally push)
  uses: ./
  with:
    push: ${{ github.event_name != 'pull_request' }}

---

Inputs

Name	Description	Required	Default
image_name	Image name (lowercase). Defaults to repo name.	No	"" (computed from repo name)
context	Build context.	No	"."
file	Path to Dockerfile.	No	"Dockerfile"
platforms	Target platforms.	No	"linux/amd64,linux/arm64"
build_args	Build args, one per line: KEY=VALUE.	No	""
name_suffix	Optional suffix for image name, e.g. -frontend.	No	""
extra_tags	Extra tags (newline‑separated, forwarded to metadata action).	No	""
push	Whether to push to GHCR.	No	"true"
use_cache	Use GitHub Actions cache for buildx.	No	"true"

---

Permissions & Auth

Add to your workflow (already in the example):

permissions:
  contents: read
  packages: write

The action logs into ghcr.io with GITHUB_TOKEN; no personal access token is required.

---

Tagging behavior

Tags are generated by docker/metadata-action:

• latest on the default branch
• Branch tags for branch builds
• Tag refs for Git tags (e.g., v1.2.3)
• sha-<shortsha> for the commit
• Plus any custom extra_tags

Example outcome for tagging v1.2.3 on the default branch:

• latest, v1.2.3, and sha-<shortsha> (plus branch ref if applicable)

---

Caching

If use_cache: true, the action configures cache-from: type=gha and cache-to: type=gha,mode=max for faster rebuilds across CI runs.

---

PR vs. main behavior

• Pull Requests: typically run with push: false (via the example condition), so images are not pushed. The build result lives in the build cache.
• Main/Tags: run with push: true and publish the multi‑arch image to GHCR.

You can optionally load a single‑arch image in PRs by switching to platforms: linux/amd64 and using load: true in your own wrapper step if needed.

---

Requirements

• Dockerfile present at the configured path.
• Repository has packages: write permission in the workflow.
• The GHCR namespace you target (ghcr.io/agile-software-engineering-25/<image>) exists or is creatable by your repo’s GITHUB_TOKEN.

---

Troubleshooting

• Warning: “No output specified with docker-container driver…”
  • This appears when you’re not pushing (e.g., PR builds). It’s expected; the image exists only in the cache. On publish builds (push: true) this warning does not appear and the image is pushed to GHCR.
• Image not visible in GHCR
  • Ensure the workflow has packages: write permission and the uses: docker/login-action@v3 step ran.
  • Confirm the image path is correct for your setup.

---

Where to find the image

After a publish build, go to [Packages] (https://github.com/orgs/Agile-Software-Engineering-25/packages) in GitHub and look for the image under ghcr.io with the tags from the build run.

Repo

Look here to see the [repo] (https://github.com/Agile-Software-Engineering-25/build-and-publish-image)