feat(go-release): require compiled build identity on every primary image

[fredcamaral]

GitHub Actions Shared Workflows

---

Merge on hold. This PR stays open until the matcher decision is taken: matcher (go-release@tier-2) has not adopted the build identity yet, and promoting this rule to tier-2 would fail its next release. Do not merge before that.

Description

Affects go-release.yml and its docs. build.yml is unchanged.

Every Go service image released through go-release.yml must now prove its compiled build identity. Until now the primary build forwarded the caller's require_build_identity (default false), so a primary Dockerfile without ARG REVISION published with a warning. From this release:

• Primary image: no opt-out. The primary build passes require_build_identity: true to build.yml as a literal. A primary Dockerfile without ARG REVISION fails the build with the existing error pointing at docs/build.md § Build identity contract; one that declares it is interrogated with docker run <image> --version before the push, as today.
• require_build_identity input: kept, default true, now only the default for extra_builds groups. A group without its own key inherits it, so a group whose image carries no Go binary (a migrate/migrate migrations image, a UI, a Node MCP) sets "require_build_identity": false. The input is not removed: 35 repos pass it explicitly, and an unknown input fails workflow_call.
• build.yml: unchanged. Its input still defaults to false. Its direct callers publish TypeScript and Python images, which do not carry the contract.

Docs: docs/go-release.md (input row, § Build identity, per-group key), docs/build.md § Build identity contract → Adoption, docs/tiers.md § Build identity verification. The tiers doc promised "once every consumer has adopted, verification becomes unconditional, and that release will be announced before it is cut"; the release note below is that announcement.

What changes for consumers

Caller	When the rule arrives	What happens
@tier-0 / @tier-1 / @tier-2	At the promotion of the release carrying this change (tier-0 automatic; tier-1 and tier-2 after the Environment approval)	Next tag: primary image verified or failed. A caller that already passes require_build_identity: true sees no change, groups included
Fixed @vX.Y.Z or SHA pin	On the pin bump that crosses this release	Same, from that bump on. Until then, nothing changes
Caller that omits the input	As above	Primary required, and every extra_builds group without an explicit false required too
GoReleaser-only caller (enable_goreleaser: true, both registries off)	Never	The image build job does not run, so there is nothing to verify

Consumer sweep (2026-09-26 ~01:50Z)

GraphQL sweep of .github/workflows/* on develop, main and the default branch of all 317 LerianStudio repos, archived included: 79 caller jobs in 47 repos.

• Every tier-* caller on develop passes require_build_identity: true, except:
  • matcher (tier-2): input absent, no Dockerfile declares ARG REVISION, groups ui/migrations/mcp have no key. Its next tag after the tier-2 promotion would fail. This is the hold above.
  • lerian-cli (tier-1): GoReleaser only, no image. Unaffected.
• Every fixed pin on develop passes true, so the bump changes nothing for them.
• Stable line not yet released on four tier-* callers: go-boilerplate-ddd, go-boilerplate-ddd-fullstack, ungoliant-controller (tier-0) and billing-worker (tier-2) adopted on develop, but their main has not had a stable release since. A hotfix/* tag cut from today's main after the promotion would fail (primary without ARG REVISION; the ungoliant allure and billing-worker migrations groups also inherit the new default). A regular develop → main release carries the adoption. Cut those four releases before promoting.
• Archived repos and test repos (v1.43.0 pins) are ignored.

Type of Change

• feat: New workflow or new input/output/step in an existing workflow
• fix: Bug fix in a workflow (incorrect behavior, broken step, wrong condition)
• perf: Performance improvement (e.g. caching, parallelism, reduced steps)
• refactor: Internal restructuring with no behavior change
• docs: Documentation only (README, docs/, inline comments)
• ci: Changes to self-CI (workflows under .github/workflows/ that run on this repo)
• chore: Dependency bumps, config updates, maintenance
• test: Adding or updating tests
• BREAKING CHANGE: Callers must update their configuration after this PR

Breaking Changes

None for any adopted caller. Committed as feat without !: no tier-* caller breaks when this merges, because the rule reaches it only at promotion, and the promotion waits on the sweep above. A fixed-pin caller sees the rule only when it bumps the pin, and the release note says so. A caller that has not adopted must add the three ARG lines and the buildinfo calls in main (docs/build.md § Build identity contract) before it takes the release, and mark non-Go extra_builds groups with "require_build_identity": false.

Release note

go-release: compiled build identity is now mandatory for the primary image. Every image the primary go-release.yml build publishes must answer docker run <image> --version with the release version and the commit it was built from; a primary Dockerfile that does not declare ARG REVISION now fails the build instead of publishing with a warning. require_build_identity stays as an input, defaults to true, and only sets the default for extra_builds groups: mark a group whose image has no Go binary (migrations, UI, Node) with "require_build_identity": false. @tier-N callers receive this at the promotion of this release; fixed @vX.Y.Z pins on their next bump. build.yml is unchanged. Adoption: docs/build.md § Build identity contract.

Testing

• YAML syntax validated locally: actionlint clean on go-release.yml; yamllint -c .yamllint.yml reports only the pre-existing line-length and comment-spacing warnings; typos clean on the four changed files
• bash tests/go-release/test-workflow.sh (5/5), bash tests/build-identity/test-workflow.sh (33/33), python3 src/validate/ungoliant-release-diff/test.py (19/19)
• Triggered a real workflow run on a caller repository using @this-branch or the beta tag: not done here; after the merge, the first tag of an adopted tier-0 caller on the promoted release shows the step running without opt-in
• Verified all existing inputs still work with default values
• Confirmed no secrets or tokens are printed in logs
• Checked that unrelated workflows are not affected

Caller repo / workflow run: pending the first tag after promotion.

Related Issues

Closes the build identity rollout ("wave D"): follows #826 (verification in build.yml) and #827 (per-group boolean overrides).

🤖 Generated with Claude Code

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: LerianStudio/github-actions-shared-workflows/.coderabbit.yml

Review profile: ASSERTIVE

Plan: Essentials

Run ID: 8311951f-75b6-467b-b07b-6eca7c4540ce

📥 Commits

Reviewing files that changed from the base of the PR and between d6fb81c and 04bbf65.

📒 Files selected for processing (4)

• .github/workflows/go-release.yml
• docs/build.md
• docs/go-release.md
• docs/tiers.md

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

---

Walkthrough

go-release.yml now always requires build identity for its primary image. Its top-level input defaults to true for extra build groups unless a group overrides it. Documentation describes this behavior and distinguishes it from direct build.yml callers.

Changes

Build identity requirement

Layer / File(s)	Summary
Set and document build identity requirements .github/workflows/go-release.yml, docs/build.md, docs/go-release.md, docs/tiers.md	The primary build always requires identity. Extra build groups default to requiring identity but can override the setting. The documentation describes missing ARG REVISION behavior for workflow and direct build callers.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Suggested reviewers: bedatty

Merge Risk: ⚪ Minimal · up to 04bbf

No demonstrated issue in this change blocks merging. Complete the planned caller adoption and validation before promoting the release to those callers.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary workflow change: compiled build identity is now required for every primary image.
Description check	✅ Passed	The description is detailed and covers the change, affected workflows, consumer impact, migration guidance, testing, known rollout blockers, and related issues. It explicitly records that a real calle…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}

[lerian-studio]

🔍 Lint Analysis

Check	Files Scanned	Status
YAML Lint	1 file(s)	✅ success
Action Lint	1 file(s)	✅ success
Pinned Actions	1 file(s)	✅ success
Markdown Link Check	3 file(s)	✅ success
Spelling Check	4 file(s)	✅ success
Shell Check	1 file(s)	✅ success
README Check	1 file(s)	✅ success
Composite Schema	no changes	⏭️ skipped
Deployment Matrix	no changes	⏭️ skipped

---

_{🔍 View full scan logs}

[lerian-studio]

🛡️ CodeQL Analysis Results

Languages analyzed: actions

Found 1 issue(s): 1 Medium

Severity	Rule	File	Message
🟡 Medium	actions/untrusted-checkout/medium	.github/workflows/go-release.yml:602	Potential unsafe checkout of untrusted pull request on non-privileged workflow.

---

_{🔍 View full scan logs | 🛡️ Security tab}

[lerian-studio]

🔍 PR Validation Summary

✅ PR Mergeable — no blocking failures

Check	Status	Blocking
Source Branch	✅ success	yes
PR Title	✅ success	yes
PR Description	✅ success	yes
Breaking Change Guard	✅ success	yes
Commit Signatures	✅ success	yes
PR Size	✅ success	no
Auto Labels	✅ success	no
PR Metadata	✅ success	no

---

_{🔍 View workflow run}

[lerian-studio]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.