egress-proxies-operator/docs/plans/2026-08-11-1935-gitea-build-workflow.md

Plan: Distilled Gitea Actions image-build workflow

Created: 2026-08-11 19:35

Context

This repo (egress-proxies-operator) has a Dockerfile, a Makefile with docker-build/docker-push targets, and a Gitea remote — but no CI workflow (CLAUDE.md flags this as a TODO). A survey of all projects under /Users/jan.novak/srv found 9 image-build workflows, all variations of one lineage: trigger on workflow_dispatch + tag push, docker login to gitea.home.hrajfrisbee.cz with secrets.REGISTRY_TOKEN, raw docker build/docker push, runs-on: ubuntu-latest, permissions: {contents: read, packages: write}.

The best individual ideas are scattered:

• aviso_v2: quality-gate job before build; computes sha-<short> as a second immutable tag via $GITHUB_OUTPUT.
• gateway-helper-operator (closest sibling — same kubebuilder shape): passes build args (GIT_COMMIT etc.), tags :latest alongside the version tag.
• psmf-data-sync test.yaml: actions/setup-go@v5 with go-version-file: go.mod + module cache (proven to work on the act_runner).

Goal: distill these into one build.yaml for this repo. User decisions: triggers = tags + manual dispatch only (house convention, no builds from main); build tool = raw docker CLI (the runner bind-mounts docker.sock, so this just works); lightweight test gate (go vet + go build + go test -short, no envtest download); amd64 only.

The workflow

Create .gitea/workflows/build.yaml:

name: Build and Push

on:
  workflow_dispatch:
    inputs:
      tag:
        description: 'Image tag'
        required: true
        default: 'latest'
  push:
    tags:
      - '*'

concurrency:
  group: build-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true
      - name: Vet
        run: go vet ./...
      - name: Build
        run: go build ./...
      - name: Test (short)
        run: go test -short ./...

  build:
    needs: check
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4

      - name: Compute image tags
        id: meta
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            TAG="${{ inputs.tag }}"
          else
            TAG="${{ github.ref_name }}"
          fi
          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
          echo "sha=sha-$(echo '${{ github.sha }}' | cut -c1-12)" >> "$GITHUB_OUTPUT"

      - name: Login to Gitea registry
        run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login -u ${{ github.actor }} --password-stdin gitea.home.hrajfrisbee.cz

      - name: Build and push
        run: |
          IMAGE=gitea.home.hrajfrisbee.cz/${{ github.repository }}
          docker build \
            --build-arg GIT_COMMIT=$(echo '${{ github.sha }}' | cut -c1-12) \
            --label org.opencontainers.image.source=https://gitea.home.hrajfrisbee.cz/${{ github.repository }} \
            --label org.opencontainers.image.created=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
            -t "$IMAGE:${{ steps.meta.outputs.tag }}" \
            -t "$IMAGE:${{ steps.meta.outputs.sha }}" \
            .
          docker push "$IMAGE:${{ steps.meta.outputs.tag }}"
          docker push "$IMAGE:${{ steps.meta.outputs.sha }}"

      - name: Push latest (tag builds only)
        if: github.event_name == 'push'
        run: |
          IMAGE=gitea.home.hrajfrisbee.cz/${{ github.repository }}
          docker tag "$IMAGE:${{ steps.meta.outputs.tag }}" "$IMAGE:latest"
          docker push "$IMAGE:latest"

What's distilled vs. improved over the existing workflows

Distilled (house patterns kept as-is): triggers, REGISTRY_TOKEN + github.actor login, image name gitea.home.hrajfrisbee.cz/${{ github.repository }}, ubuntu-latest, raw docker CLI, permissions block.

Improvements none of the existing workflows have all of:

1. sha-<12> immutable tag alongside the human tag (aviso_v2 had this; nobody else) — lets deployments pin exactly what was built.
2. Test gate (aviso_v2 had one; the Go projects don't) — lightweight variant per user choice; uses go-version-file: go.mod so the Go version never drifts from the module.
3. GIT_COMMIT build arg matches the Makefile/Dockerfile contract — the binary's internal/version.Commit and the org.opencontainers.image.revision label get the real commit (12-char, same width as the Makefile's git rev-parse --short=12; no -dirty needed since CI checkouts are clean).
4. :latest only on real tag pushes, not manual dispatch — gateway-helper pushed latest unconditionally, which lets an ad-hoc dispatch of an old ref clobber latest.
5. concurrency group — cancels a superseded run of the same ref (none of the 20 surveyed workflows have this).
6. OCI source/created labels added at build time (revision label already comes from the Dockerfile).

Files

• Create .gitea/workflows/build.yaml — content above.
• Update CLAUDE.md — replace the TODO: no .gitea/workflows/ CI pipeline exists yet note in the Git Commits section with a short CI/CD subsection describing the workflow (triggers, secret, tags produced).
• Update CHANGELOG.md — new top entry (after user confirms it works, per convention; timestamp via date "+%Y-%m-%d %H:%M %Z").
• Copy this plan to docs/plans/YYYY-MM-DD-HHMM-gitea-build-workflow.md (timestamp via date "+%Y-%m-%d-%H%M") and commit it first, per CLAUDE.md ordering rule.

Branch & MR

House convention: feature → own branch + MR. Dockerfile and cmd/ already exist on main, so:

1. git checkout -b feat/gitea-build-workflow origin/main (do not touch the current feat/proxy-operator branch's uncommitted .claude/settings.json change — leave it be).
2. Commit plan file, then the workflow + CLAUDE.md update (with Co-Authored-By: Claude <noreply@anthropic.com>).
3. git push -u origin feat/gitea-build-workflow, open MR with tea pr create --base main --head feat/gitea-build-workflow. Do not merge.

Note: main has no internal//test/ dirs yet (those are on feat/proxy-operator), which is fine — the workflow only fires on tags/dispatch, and by then the operator branch will be merged. go build ./... / go test -short ./... work on both branch states.

Prerequisite (user action)

REGISTRY_TOKEN secret must exist in this repo's Gitea settings (Settings → Actions → Secrets): a personal access token with write:package scope — same as every other project uses. Flag this in the MR description.

Verification

The workflow doesn't trigger on branch pushes, so end-to-end verification happens after merge:

1. Local sanity: docker build --build-arg GIT_COMMIT=test -t scratch-check . (confirms the build args/labels line is valid) — or at minimum a YAML parse check.
2. After the MR merges: run the workflow manually via Gitea UI (Actions → Build and Push → Run workflow, tag manual-test), confirm both manual-test and sha-… tags appear under Packages, and that :latest was NOT updated.
3. Then push a real version tag (e.g. v0.1.0) and confirm v0.1.0, sha-…, and latest all appear.