feat(gitops): annotate-only mode for Flux image automation

[monotek]

What

Adds an annotate-only mode to update_file: when a gitops-dev/gitops-stage/gitops-prod line provides a path only (no field), the action writes the deploy.staffbase.com/* annotations without updating the image tag.

The image-update block is now guarded on a non-empty field; the annotation writes stay unconditional. The line parser already leaves field empty for a path-only line, so no parser change was needed.

# annotate only — image tag owned by Flux image automation
gitops-stage: |-
  kubernetes/namespaces/my-service/stage/de1/my-service-helm.yaml

Why

Staffbase is migrating apps from the apperator Application CR to the staffbase-application Helm chart (HelmRelease overlays in mops). In the new model the image tag is owned by Flux image automation (ImageRepository/ImagePolicy/ImageUpdateAutomation), which scans the registry and commits the tag: line back to mops itself.

So for migrated apps this action must stop writing the tag — but must keep writing the annotations. flux-deployment-reporter reads commitSha + repositoryFullName off the reconciled resource to report deployments to Swarmia for DORA metrics, and those are build-time facts only this action knows (image automation only ever knows the tag, never the source commit/repo). Keeping this action as the annotation-writer also yields a full commit SHA in every environment, including prod, where tags are CalVer (2025.50.14) and carry no SHA.

Known transient skew

version is still set to INPUT_TAG (the freshly built tag). It may briefly lead the actual tag: until image automation selects the new build. It converges, and the reporter dedupes on (commitSha, version), so it self-heals.

Backward compatibility

The two-token <path> <field> form is unchanged — image update and annotations, exactly as today. Apperator apps still mid-migration keep working. No new required input; the path-only line is the trigger.

Tests

• update_file with empty field: skips image update, still writes all three annotations (mock + real-yq integration on the helmrelease.yaml fixture, asserting the tag: is untouched).
• update_file with field: regression test that the tag is updated and annotations written.
• process_file_updates path-only line end-to-end.
• Full suite green (84 tests), shellcheck clean.

Out of scope

The reporter change to list HelmRelease (helm.toolkit.fluxcd.io/v2) in addition to the apperator Application CR is handled separately in the flux-deployment-reporter repo — the annotation keys/values are identical regardless of resource kind, so no change is needed here.

Dependency

• https://github.com/Staffbase/flux-deployment-reporter/pull/41

[Copilot]

Pull request overview

This PR adds an annotate-only mode for GitOps updates so the action can stamp deploy.staffbase.com/* deployment annotations even when Flux image automation owns the tag: field and should not be modified by this action.

Changes:

• Guard image/tag updates in update_file behind a non-empty <field> while keeping annotation writes unconditional.
• Add unit + integration Bats coverage for both annotate-only and existing field-based update behavior.
• Document the new path-only <path> input form in the README (and clarify related inputs).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
scripts/lib/gitops-functions.sh	Adds a field-present guard so tag updates are skipped when a line is path-only, while still writing deployment annotations.
tests/lib-gitops-functions.bats	Adds tests covering annotate-only mode (mocked yq + real-yq integration) and an end-to-end process_file_updates path-only case.
README.md	Documents annotate-only mode usage and updates input descriptions accordingly.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.