105 lines
3.1 KiB
Markdown
105 lines
3.1 KiB
Markdown
# 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
|
|
```
|