openrabbit/docs/DOCKER.md

Docker Build & Registry — ${REPO_NAME}

Overview

The Docker workflow (.gitea/workflows/docker.yml) builds Docker images and optionally pushes them to the Gitea Container Registry.

Gitea Container Registry Naming Convention

Gitea's registry follows this pattern:

{REGISTRY_HOST}/{OWNER}/{IMAGE}:{TAG}

Example:

git.hiddenden.cafe/myorg/myapp:1.2.3

This is different from Docker Hub (docker.io/library/myapp:latest). The workflow enforces this format automatically.

Dynamic Owner/Repo Derivation

The workflow dynamically determines the image owner and name so it works for both user repos and organization repos without hardcoding.

Logic:

1. Determine FULL_REPO from (in priority order):
   • $GITEA_REPOSITORY (Gitea native environment variable)
   • ${{ github.repository }} (Gitea Actions compatibility layer)
2. Split into OWNER (before /) and REPO (after /).
3. If IMAGE_OWNER=auto in config → use OWNER; else use the config value.
4. If IMAGE_NAME=auto in config → use REPO; else use the config value.

This means you rarely need to change IMAGE_OWNER or IMAGE_NAME.

Triggers & Push Behavior

Event	Build?	Push?	Condition
Pull Request	Yes	No	Never pushes on PRs
Push to main	Yes	Conditional	DOCKER_PUSH=true AND DOCKER_PUSH_ON_BRANCH=true
Tag v1.2.3	Yes	Conditional	DOCKER_PUSH=true AND DOCKER_PUSH_ON_TAG=true

Safe default: DOCKER_PUSH=false — images are built but never pushed.

Tag Strategy

Controlled by DOCKER_TAG_STRATEGY in .ci/config.env:

semver+latest (default)

• Tag v1.2.3 → pushes :1.2.3 and :latest
• Push to main → pushes :main

semver

• Tag v1.2.3 → pushes :1.2.3 only
• Push to main → pushes :main

branch

• Branch pushes only, tagged as :branchname

Required Secrets

To push images, set these secrets in your Gitea repository (Settings → Actions → Secrets):

Secret	Description
REGISTRY_USERNAME	Gitea username or bot account name
REGISTRY_TOKEN	Personal Access Token with package:write scope

Creating a PAT

1. Go to Settings → Applications → Generate New Token
2. Name: e.g., ci-docker-push
3. Scopes: select package (read + write)
4. Copy the token and add it as REGISTRY_TOKEN in repo secrets

Why PAT instead of job token? Gitea Actions job tokens may not have sufficient permissions for the container registry in all configurations. PATs are the recommended approach.

Detection

The workflow auto-detects how to build:

1. Dockerfile → docker build -t <image>:<tag> .
2. docker-compose.yml → docker compose build
3. Neither → exits 0 with a message (graceful skip)

Enabling Docker Push

1. Set DOCKER_PUSH=true in .ci/config.env
2. Add REGISTRY_USERNAME and REGISTRY_TOKEN secrets
3. Push a commit or tag — the workflow will build and push

Pulling Images

After pushing, pull images with:

docker pull git.hiddenden.cafe/<owner>/<repo>:latest