# 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:
```bash
docker pull git.hiddenden.cafe/<owner>/<repo>:latest
```