image-builder

Reusable Gitea Actions workflow for building and pushing container images using Kaniko. No Docker daemon required — Kaniko runs directly on the runner host and handles both build and push in a single step.

How It Works

Calling repo (e.g. ansible/ansible-runner)
  → workflow_call → docker/image-builder
    → Kaniko builds Dockerfile
    → Pushes to gitea.mod.home/<calling_org>/<image_name>:latest
    → Pushes to gitea.mod.home/<calling_org>/<image_name>:<sha>

Kaniko is available on the runner host via the tools EmptyDir volume, populated by the install-build-tools initContainer in the act runner deployment.

Usage

Minimal — push to Gitea Registry

# .gitea/workflows/build-myimage.yaml in your repo
name: 🏗️ Build My Image

on:
  push:
    branches: [main]
    paths:
      - 'docker/Dockerfile'
  workflow_dispatch:

jobs:
  build:
    uses: docker/image-builder/.gitea/workflows/build.yaml@main
    with:
      image_name: my-image            # → gitea.mod.home/<your_org>/my-image
      dockerfile_path: docker/Dockerfile
      context_path: docker/
    secrets:
      TOKEN: ${{ secrets.TOKEN }}

With extra tag

jobs:
  build:
    uses: docker/image-builder/.gitea/workflows/build.yaml@main
    with:
      image_name: my-image
      dockerfile_path: docker/Dockerfile
      context_path: docker/
      extra_tag: stable
    secrets:
      TOKEN: ${{ secrets.TOKEN }}

Push to Docker Hub

jobs:
  build:
    uses: docker/image-builder/.gitea/workflows/build.yaml@main
    with:
      image_name: myuser/my-image
      registry: registry-1.docker.io
      dockerfile_path: docker/Dockerfile
      context_path: docker/
    secrets:
      TOKEN: ${{ secrets.TOKEN }}
      REGISTRY_USER_OVERRIDE: ${{ secrets.DOCKERHUB_USER }}
      REGISTRY_PASSWORD_OVERRIDE: ${{ secrets.DOCKERHUB_TOKEN }}

Force rebuild without cache

    with:
      image_name: my-image
      dockerfile_path: docker/Dockerfile
      context_path: docker/
      no_cache: true

Inputs

Input	Required	Default	Description
`image_name`	✅	—	Image name without registry/org
`dockerfile_path`	✅	—	Path to Dockerfile relative to repo root
`context_path`	✅	—	Build context directory relative to repo root
`registry`	❌	`gitea.mod.home`	Target registry
`image_org`	❌	calling repo owner	Registry org/namespace
`extra_tag`	❌	`''`	Additional tag besides `latest` and SHA
`no_cache`	❌	`false`	Disable Kaniko build cache

Secrets

Secret	Required	Description
`TOKEN`	✅	Gitea access token for checkout
`REGISTRY_USER_OVERRIDE`	❌	Override registry username
`REGISTRY_PASSWORD_OVERRIDE`	❌	Override registry password

Secrets REGISTRY_USER and REGISTRY_PASSWORD must be set at the docker org level in Gitea. All other repos inherit them automatically.

Required Secrets (docker Org)

Set these in Gitea → docker org → Settings → Secrets:

Secret	Description
`REGISTRY_USER`	Gitea username for container registry login
`REGISTRY_PASSWORD`	Gitea access token with `package:write` scope
`TELEGRAM_BOT_TOKEN`	Telegram bot token for build notifications
`TELEGRAM_CHAT_ID`	Telegram chat ID for build notifications

Runner Requirements

The act runner deployment must have the install-build-tools initContainer which copies the Kaniko executor binary into the tools EmptyDir volume:

initContainers:
  - name: install-build-tools
    image: gcr.io/kaniko-project/executor:latest
    command:
      - /bin/sh
      - -c
      - cp /kaniko/executor /tools/executor && chmod +x /tools/executor
    volumeMounts:
      - name: tools
        mountPath: /tools

The runner must have the docker label registered:

# configmap.yaml
labels:
  - "docker:host"

Image Naming Convention

Calling repo	image_name	Result
`ansible/ansible-runner`	`ansible-act-runner`	`gitea.mod.home/ansible/ansible-act-runner:latest`
`ansible/ansible-runner`	`ubuntu-act-runner`	`gitea.mod.home/ansible/ubuntu-act-runner:latest`
any repo	`myimage` with `image_org: shared`	`gitea.mod.home/shared/myimage:latest`

Roadmap

TLS for Gitea registry — remove --insecure flag once cert-manager CA is in place
Multi-arch builds via Kaniko cross-compilation