ci-actions/docker-build/README.md

docker-build

Build and push Docker images with S3 caching and optional Nix cache support.

Features

• S3 build cache: Uses your self-hosted S3 (SeaweedFS) for fast layer caching
• Nix cache integration: Automatically configures Attic cache for Dockerfiles using Nix
• Auto-tagging: Smart tagging based on branches, PRs, and semver tags
• Multi-registry support: Works with Forgejo Docker registry or any other

Usage

Basic example

name: Build Docker Image
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: https://git.toph.so/toph/ci-actions/docker-build@main
        with:
          dockerfile: ./Dockerfile
          image-name: git.toph.so/${{ gitea.repository }}
          registry-password: ${{ secrets.GITEA_TOKEN }}

With Nix cache support

For Dockerfiles that use Nix/Lix (e.g., FROM ghcr.io/lix-project/lix):

- uses: https://git.toph.so/toph/ci-actions/docker-build@main
  with:
    dockerfile: ./Dockerfile.nix
    image-name: git.toph.so/${{ gitea.repository }}/nix
    registry-password: ${{ secrets.GITEA_TOKEN }}
    enable-nix-cache: 'true'

Multiple images from one repo

jobs:
  build-web:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: https://git.toph.so/toph/ci-actions/docker-build@main
        with:
          dockerfile: ./deploy/Dockerfile
          image-name: git.toph.so/${{ gitea.repository }}
          registry-password: ${{ secrets.GITEA_TOKEN }}

  build-worker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: https://git.toph.so/toph/ci-actions/docker-build@main
        with:
          dockerfile: ./deploy/Dockerfile.worker
          image-name: git.toph.so/${{ gitea.repository }}/worker
          registry-password: ${{ secrets.GITEA_TOKEN }}

Custom tags

- uses: https://git.toph.so/toph/ci-actions/docker-build@main
  with:
    dockerfile: ./Dockerfile
    image-name: git.toph.so/myorg/myapp
    registry-password: ${{ secrets.GITEA_TOKEN }}
    tags: |
      git.toph.so/myorg/myapp:latest
      git.toph.so/myorg/myapp:v1.0.0
      git.toph.so/myorg/myapp:stable

Inputs

Input	Required	Default	Description
dockerfile	✅	-	Path to Dockerfile
image-name	✅	-	Full image name (e.g., git.toph.so/user/repo)
registry-password	✅	-	Registry password/token
context	❌	.	Build context path
registry	❌	git.toph.so	Docker registry
registry-username	❌	${{ gitea.actor }}	Registry username
push	❌	true	Push image to registry
tags	❌	auto-generated	Custom tags (newline-separated)
s3-cache-bucket	❌	docker-cache	S3 bucket for build cache
s3-endpoint	❌	https://s3.toph.so	S3 endpoint URL
enable-nix-cache	❌	false	Configure Nix binary cache
attic-endpoint	❌	https://cache.toph.so	Attic/Nix cache endpoint

Auto-generated tags

When tags input is not provided, tags are auto-generated based on the event:

Event	Generated tags
Push to main	main, <short-sha>
Push tag v1.2.3	1.2.3, 1.2, 1, latest, <short-sha>
Pull request #42	pr-42, <short-sha>

S3 Cache

The action uses your self-hosted S3 (SeaweedFS) for Docker build cache layers, which:

• Speeds up builds by reusing unchanged layers
• Works across different runners and workflow runs
• Automatically managed by Docker Buildx

No additional setup required — the cache is automatically used if S3 is accessible.

Nix Cache Integration

When enable-nix-cache: 'true', the action configures:

• cache.nixos.org (official Nix cache)
• cache.toph.so/ci (your CI cache, 90d retention)
• cache.toph.so/toph (your trusted cache, 180d retention)

This allows Dockerfiles using Nix to fetch pre-built derivations instead of rebuilding from source.

Prerequisites

For all builds:

• S3 service running at s3.toph.so (SeaweedFS)
• GITEA_TOKEN secret configured (auto-available in Forgejo Actions)

For Nix-enabled builds:

• Attic cache service running at cache.toph.so

Examples

See the main ci-actions README for infrastructure setup details.