Merge pull request 'Add Gitea Actions image-build workflow' (#2) from feat/gitea-build-workflow into main

Reviewed-on: #2

.gitea/workflows/build.yaml

@@ -0,0 +1,76 @@
+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 }}"
+
+      # Only real tag pushes move :latest — an ad-hoc dispatch of an old ref must not clobber it.
+      - 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"

CLAUDE.md

@@ -199,8 +199,18 @@ Always append a `Co-Authored-By` trailer to indicate AI assistance:
 
     Co-Authored-By: Claude <noreply@anthropic.com>
 
-TODO: no `.gitea/workflows/` CI pipeline exists yet — add a CI/CD subsection here once
-one is set up.
+### CI/CD
+
+`.gitea/workflows/build.yaml` builds the manager image and pushes it to the Gitea
+registry. Triggers: any tag push, or manual `workflow_dispatch` with a `tag` input.
+A lightweight `check` job (`go vet` / `go build` / `go test -short`) gates the build.
+
+- Images: `gitea.home.hrajfrisbee.cz/kacerr/egress-proxies-operator:<tag>` plus an
+  immutable `sha-<12-char-commit>` tag on every build; `:latest` moves only on real
+  tag pushes, never on manual dispatch.
+- Requires the `REGISTRY_TOKEN` repo secret (Gitea PAT with `write:package`),
+  same convention as the other projects on this Gitea instance.
+- The commit is baked into the binary via the `GIT_COMMIT` build arg (see Dockerfile).
 
 ## Gotchas
 

README.md

@@ -167,6 +167,40 @@ cloud.google.com/go/compute v1.65.0. envtest uses the 1.36.2 binary
 bundle (the latest 1.36 patch with published binaries — do not "fix" the
 Makefile's derived version to 1.36.3, which has none).
 
+## Gitea CI
+
+[.gitea/workflows/build.yaml](.gitea/workflows/build.yaml) builds the
+manager image and pushes it to this Gitea instance's container registry.
+It runs on **any tag push** or manually via **Run workflow** (with a `tag`
+input) — never on branch pushes. A lightweight `check` job (`go vet`,
+`go build`, `go test -short`) gates the build.
+
+Every build pushes two tags to
+`gitea.home.hrajfrisbee.cz/kacerr/egress-proxies-operator`:
+
+- the human tag (the git tag, or the dispatch input), and
+- an immutable `sha-<12-char-commit>` tag — pin deployments to this one.
+
+`:latest` is additionally updated on real tag pushes only, so a manual
+dispatch of an old ref can never clobber it. The commit is baked into the
+binary (`internal/version.Commit`) via the `GIT_COMMIT` build arg.
+
+### Mandatory Gitea secrets
+
+Set under **Settings → Actions → Secrets** in this repo:
+
+| Secret           | Required by                   | What it is                               |
+| ---------------- | ----------------------------- | ---------------------------------------- |
+| `REGISTRY_TOKEN` | `build.yaml` (registry login) | Gitea PAT with the `write:package` scope |
+
+The token is paired with `${{ github.actor }}` as the username, so it
+must belong to the user triggering the workflow — same convention as the
+other projects on this instance.
+
+Without `REGISTRY_TOKEN` the `check` job still passes but the build job
+fails at the `docker login` step. No other secrets are needed — the
+workflow does not deploy anywhere.
+
 ## Development
 
 ```sh

docs/plans-executions/2026-08-11-1935-gitea-build-workflow.md

@@ -0,0 +1,53 @@
+# Execution: Distilled Gitea Actions image-build workflow
+
+Plan: `docs/plans/2026-08-11-1935-gitea-build-workflow.md`
+
+- [x] Step 1 — Create `.gitea/workflows/build.yaml`
+- [x] Step 2 — Replace CLAUDE.md CI TODO with a CI/CD subsection
+- [x] Step 3 — Push branch + open MR
+- [ ] Step 4 — CHANGELOG entry (after the first successful run is confirmed)
+
+## Steps 1–2 — workflow + CLAUDE.md
+
+The workflow distills the house pattern from 9 sibling projects (survey in the plan)
+plus improvements none of them combine: an immutable `sha-<12>` tag, a lightweight
+test gate, `:latest` moving only on real tag pushes, and a `concurrency` group.
+
+Work happened in a git worktree off `origin/main` so the main checkout (which had
+unrelated uncommitted changes) stayed untouched:
+
+```bash
+git worktree add -b feat/gitea-build-workflow \
+  "$SCRATCH/wt-build" origin/main
+```
+
+Deviation from the plan's assumptions: while planning, `feat/proxy-operator` was
+still unmerged and the plan noted `main` lacked `internal/`/`test/`. By execution
+time `origin/main` had moved (`076bc66..f7000f7` — the proxy-operator MR merged),
+so the branch and its CI gate cover the full operator code.
+
+Verified the workflow parses and the check-gate commands pass on this exact tree
+(ruby stands in for a YAML linter because the system python3 has no `yaml` module):
+
+```bash
+ruby -ryaml -e "YAML.load_file('.gitea/workflows/build.yaml'); puts 'YAML OK'"
+go vet ./... && go build ./... && go test -short ./...   # all packages ok
+```
+
+## Step 3 — push + MR
+
+Branch pushed and MR opened with `tea` (the worktree was then removed and the main
+checkout switched onto the branch so the files are visible locally):
+
+```bash
+tea pr create --title "Add Gitea Actions image-build workflow" \
+  --description "..." --base main --head feat/gitea-build-workflow
+# → https://gitea.home.hrajfrisbee.cz/kacerr/egress-proxies-operator/pulls/2
+```
+
+Worth noting: the workflow itself cannot run end-to-end until (a) the MR merges
+(it only triggers on tags / manual dispatch, not branch pushes) and (b) the
+`REGISTRY_TOKEN` secret is created in this repo's Gitea settings (PAT with
+`write:package`). First real verification = manual dispatch with tag
+`manual-test`, expecting `manual-test` + `sha-…` in Packages and `:latest`
+untouched.

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-<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`:
+
+```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.