From 849ec1083ecc111f2f4b708b628895657af10ff7 Mon Sep 17 00:00:00 2001 From: Jan Novak Date: Tue, 11 Aug 2026 19:37:42 +0200 Subject: [PATCH] Add plan: distilled Gitea Actions image-build workflow Co-Authored-By: Claude --- .../2026-08-11-1935-gitea-build-workflow.md | 135 ++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 docs/plans/2026-08-11-1935-gitea-build-workflow.md diff --git a/docs/plans/2026-08-11-1935-gitea-build-workflow.md b/docs/plans/2026-08-11-1935-gitea-build-workflow.md new file mode 100644 index 0000000..199c27a --- /dev/null +++ b/docs/plans/2026-08-11-1935-gitea-build-workflow.md @@ -0,0 +1,135 @@ +# 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-` 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`: + +```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 `). +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.