# Plan: Gitea Action to open a gitops image-update PR for fuj-management

## Context

The Go image of this app is built and pushed by the `build-go` job in
[.gitea/workflows/build.yaml](.gitea/workflows/build.yaml), tagged
`gitea.home.hrajfrisbee.cz/kacerr/fuj-management:<git-tag>-go` (e.g. `0.37-go`).

Kubernetes manifests live in a **separate** repo,
`gitea.home.hrajfrisbee.cz/kacerr/home-kubernetes`. Today, bumping the image in
the `fuj-management` Deployment (namespace `fuj`) is a manual edit there.

We want CI to automate that bump: when a new Go image is built, open a PR against
`home-kubernetes` that swaps the image to the freshly built tag — using the
`uh-cli gitops deployment update` command. The user reviews/merges that PR in
Gitea (matching the existing branch-per-change, merge-in-browser workflow).

Decisions confirmed with the user:
- **Separate workflow file** (not a job inside build.yaml).
- **New `GITOPS_TOKEN` secret** for home-kubernetes write + PR access.
- **uh-cli version pinned with a default, overridable via env/var/input.**

## How uh-cli works (from `/Users/jan.novak/srv/go/uh-cli/docs/`)

- `uh-cli gitops deployment update` clones `--git-repo`, walks `--git-path`
  recursively for a `kind: Deployment` whose `metadata.name`/`namespace` match,
  edits the first container image surgically, commits on a new branch
  `gitops/update-<name>-<timestamp>`, pushes, and **opens the PR itself** via
  `tea pr create`. PR base is always `main`; title/body are hardcoded (no flags).
- Requires on PATH: `git` and `tea` (tea only for the PR flow; `--force` skips it).
- Auth: token embedded in the `--git-repo` URL (`https://user:TOKEN@host/...`);
  `tea login add` for PR creation; git identity via `git config`/env vars.
- `--dry-run` prints the unified diff and makes no git changes. Global `-v`
  (placed **before** the subcommand) enables debug logging on stderr.
- Release binaries are named `uh-cli-<version>-linux-amd64` (version includes the
  `v`), attached to the Gitea release. Latest tag today is **`v0.1.0`**.

## Change: new workflow `.gitea/workflows/gitops-update.yaml`

Triggers:
- `workflow_run` on `workflows: ["Build and Push"]`, `types: [completed]`, gated
  to `conclusion == 'success'` — auto-fires after the image build succeeds.
- `workflow_dispatch` with inputs: `tag` (git tag without the `-go` suffix, e.g.
  `0.37`), `dry_run` (boolean, default false), `uh_cli_version` (optional override).

Single job `gitops-pr`, `runs-on: ubuntu-latest`, in a `container: ubuntu:latest`
for a hermetic install (matches the uh-cli CI doc pattern). Steps:

1. **Install git, curl, ca-certificates, tea** — apt-get + download tea
   `0.9.2` from `gitea.com/gitea/tea/releases/...` to `/usr/local/bin/tea`.
2. **Install uh-cli** — download
   `https://gitea.home.hrajfrisbee.cz/kacerr/uh-cli/releases/download/${UH_CLI_VERSION}/uh-cli-${UH_CLI_VERSION}-linux-amd64`
   to `/usr/local/bin/uh-cli`.
   `UH_CLI_VERSION: ${{ inputs.uh_cli_version || vars.UH_CLI_VERSION || 'v0.1.0' }}`.
3. **Resolve image tag** — if `workflow_dispatch`, use `inputs.tag`; else use
   `github.event.workflow_run.head_branch` (the pushed tag name). Output
   `gitea.home.hrajfrisbee.cz/${{ github.repository }}:<tag>-go`.
4. **Configure git identity** — `git config --global user.name/email` for the bot.
5. **Authenticate tea** — `tea login add --name ci --url https://gitea.home.hrajfrisbee.cz --token "$GITEA_TOKEN"`.
6. **Open image-update PR** — run, with `--dry-run` appended only when the
   dispatch `dry_run` input is true:
   ```
   uh-cli -v gitops deployment update \
     --deployment-name fuj-management \
     --deployment-namespace fuj \
     --set-image "<resolved image>" \
     --git-repo "https://fuj-gitops-bot:${GITEA_TOKEN}@gitea.home.hrajfrisbee.cz/kacerr/home-kubernetes" \
     --git-path gitops/home-kubernetes
   ```

`GITEA_TOKEN` is sourced from `secrets.GITOPS_TOKEN` at job level.

Job-level guard: `if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}`.

## Prerequisites (user must set up in Gitea — call out in handoff)

1. **Create `GITOPS_TOKEN` secret** in the `fuj-management` repo: a Gitea token
   for a user (`fuj-gitops-bot` or `kacerr`) that has **write + pull-request**
   access to `kacerr/home-kubernetes`. The username in the `--git-repo` URL must
   match that token's owner (adjust `fuj-gitops-bot` if using `kacerr`).
2. **uh-cli `v0.1.0` release assets must exist** (the `uh-cli-v0.1.0-linux-amd64`
   binary attached to the release). If not yet published, cut that release in the
   uh-cli repo first, or set `UH_CLI_VERSION` to a published tag.
3. **Confirm the manifest path**: `--git-path gitops/home-kubernetes` must contain
   the `fuj-management` Deployment; `--deployment-namespace fuj` disambiguates.
   Cannot verify from this repo — verify against home-kubernetes (narrow the path
   if uh-cli reports an ambiguity error).

## Files

- **New**: `.gitea/workflows/gitops-update.yaml` (the workflow above).
- After it works: prepend a `CHANGELOG.md` entry; save this plan to
  `docs/plans/<ts>-gitops-pr-action.md` per CLAUDE.md convention.

## Branching

Feature work → branch `feat/gitops-pr-action` off `main`, commit with the
`Co-Authored-By` trailer, push with `-u`, open the MR with
`tea pr create --base main --head feat/gitops-pr-action`. Do not merge from CLI.

## Verification

1. **Dry run (manual)**: trigger `gitops-update.yaml` via workflow_dispatch with
   `tag=0.37`, `dry_run=true`. Confirm logs show the unified diff (image line
   `…:0.37-go`) and `-v` debug milestones; **no PR** is created.
2. **Real run (manual)**: re-trigger with `dry_run=false`. Confirm a PR appears in
   `home-kubernetes` against `main` with the image bump, and the PR URL is printed.
3. **Auto-trigger**: push a new git tag to fuj-management → `Build and Push`
   completes → `gitops-update` fires via `workflow_run` and opens the PR.
   (Note: `workflow_run`/`head_branch` behavior depends on this Gitea/act_runner
   version; if it doesn't fire, manual `workflow_dispatch` is the fallback and the
   plan still delivers the core capability.)