feat: pin func-utils image to a per-release-branch tag

[gauron99]

proposal: pin func-utils img per release so that atleast per branch we have a more stable func-utils so we are not constantly breaking older functions because of the dynamic tag we currently have everywhere

[knative-prow]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[gauron99]

@matejvasek @lkingland WDYT?

[knative-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: gauron99, lkingland

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [gauron99,lkingland]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[Copilot]

🟡 Changes recommended

The current release-branch detection in the Makefile can fall back to v2 in detached-HEAD CI checkouts, undermining the intended per-branch pinning behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR makes func embed a more stable func-utils image tag per release branch/minor version to avoid older released CLIs being broken by changes published under a floating tag.

Changes:

• Derive FUNC_UTILS_IMG from either an exact release KVER or a release-X.Y branch, otherwise defaulting to v2.
• Align local e2e image publishing (hack/images.sh) with the embedded image tag via a new make func-utils-image helper.
• Update docs and CI so func-utils images are published as v2 on main and X.Y on release-X.Y branches.

File summaries

File	Description
Makefile	Derives and embeds a per-release-branch/per-minor func-utils image tag; adds func-utils-image helper target.
hack/images.sh	Publishes locally built func-utils images using the same tag embedded into the built func binary.
docs/README.md	Adds documentation link for the func-utils image policy.
docs/func-utils-image.md	Documents tag scheme and compatibility policy for func-utils.
.github/workflows/functions.yaml	Publishes func-utils as v2 on main and X.Y on release-X.Y, including manual dispatch support.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[matejvasek]

Automated Code Review

🤖 This review was generated by Claude Code (AI). Treat findings as suggestions to verify, not verdicts.

This PR pins the func-utils image to a per-release-branch tag. It's well-constructed — the findings below are mostly low-severity robustness/consistency issues.

Findings

1. Broad release-branch gate vs. strict tag regex — .github/workflows/functions.yaml
The job-level if accepts any refs/heads/release-* ref, but the "Derive Image Tag" step only accepts ^release-([0-9]+\.[0-9]+)$ and exit 1s otherwise. A push to release-1.24.0, release-v1.24, or release-next passes the gate, runs the full build + e2e, then hard-fails at derive — turning the workflow red instead of cleanly skipping.

2. Detached-HEAD fallback yields floating v2 — Makefile
Release-tag pinning falls back to git branch --show-current, which is empty in detached-HEAD checkouts (git worktree, SHA checkout, Prow's non-TAG_RELEASE path). This silently embeds ghcr.io/knative/func-utils:v2 into a release-branch binary, defeating the pin. Official releases are safe only because release.sh passes an exact KVER.

3. workflow_dispatch republishes utils but skips CLI image — .github/workflows/functions.yaml
publish-image (ko func CLI image) gates on push && main only, while build and publish-utils-image also allow workflow_dispatch. A manual dispatch on main republishes the utils image but silently skips the CLI image.

4. FUNC_UTILS_IMG repo-path override breaks mirror mapping — hack/images.sh
images.sh reuses only the tag from make func-utils-image and hardcodes registry.localtest.me/knative/func-utils. A FUNC_UTILS_IMG override that changes the repo/registry path (the documented "always wins" override) makes the binary embed one path while images.sh pushes to another — in-cluster e2e pulls fail to resolve.

5. Scope creep: deleted "Fork CI note" — .github/workflows/functions.yaml
The PR removes the unrelated comment documenting why codecov no-ops on forks (Hamr#395 / Functions#57). Rationale is lost and unrelated to the func-utils pin.

6. Redundant if duplicated from needs — .github/workflows/functions.yaml
publish-utils-image's new if duplicates the identical condition on build, which it already declares in needs. When build skips, the job skips via needs anyway. Two copies to keep in sync.

7. Inaccurate KVER comment — Makefile
The comment says Prow passes KVER as v1.24.0, but hack/release.sh passes KVER="${TAG}" (the knative-vX.Y.Z form). No functional impact — the regex tolerates both — but the comment could mislead.

---

Highest-value items: #1 (workflow fails red instead of skipping) and #2 (pin silently defeated in detached-HEAD builds).