Rebuild with Go 1.27, track base images with Renovate, and cut a Release for every published Image #45

Closed
opened 2026-10-10 11:13:51 +00:00 by piscis · 1 comment
Owner

Problem Statement

The Image is a static Go binary, so Go's standard library (TLS, HTTP, …) ships inside it. Its build stage still uses Go 1.25, which is out of support (the supported releases are 1.27 and 1.26), so every Image we publish carries a standard library that no longer gets security fixes. Nobody noticed because Renovate only watches the Pin, not the base images the Image is built on.

Consumers also have no way to learn what changed when a new Image appears. The registry gains an X.Y.Z-rN tag and the moving tags (3.2.0, 3.2, 3, latest) move, but there is no record of why: whether Upstream moved to a new Upstream Version, or a Rebuild picked up a toolchain or base-image fix. The commit history uses Conventional Commits, but nothing turns it into release notes, and nothing checks that a pull request's title, which becomes the squash commit on main, follows the convention.

Solution

  1. Rebuild the Image with Go 1.27, as Rebuild 2 of Upstream Version v3.2.0 (Image tag 3.2.0-r2).
  2. Renovate proposes base-image updates (the Go build image and the distroless runtime base) once a week in one grouped pull request. A CI guard makes sure such a change, or any hand-made change to a base image, raises the Rebuild in the same pull request, so it actually gets published.
  3. Every published Image gets a Release on Forgejo, named exactly like its Image tag. CI creates it right after publishing. Its notes state which Upstream Version the Image builds (linking Upstream's own release notes), the Rebuild number, whether the Upstream Version changed, and the Consumer-relevant feat/fix/perf/breaking commits since the previous Release.
  4. CI rejects pull request titles that aren't Conventional Commits, since the title is what the release notes read.

The tag scheme of ADR 0003 stays as it is: the Image has no version of its own besides the Upstream Version plus the Rebuild number.

User Stories

  1. As a Consumer, I want the Image built with a supported Go toolchain, so that the TLS and HTTP code inside the binary still gets security fixes.
  2. As a Consumer on :3, I want the Go 1.27 Image to reach me by a normal pull, so that I get the fix without changing my configuration.
  3. As a Consumer pinned to an exact Rebuild, I want 3.2.0-r2 to exist as a new immutable tag, so that 3.2.0-r1 stays exactly what it was.
  4. As a maintainer, I want Renovate to propose updates to the Go build image, so that the toolchain never silently falls out of support again.
  5. As a maintainer, I want Renovate to propose updates to the distroless runtime base, so that the runtime layer stays current too.
  6. As a maintainer, I want minor Go updates (1.27 → 1.28) proposed alongside digest updates, so that I'm moved to new Go releases before the old ones go out of support.
  7. As a maintainer, I want all base-image updates grouped into one pull request at most once a week, so that each round of updates costs one Rebuild and one Release instead of several.
  8. As a maintainer, I want CI to fail a pull request that changes a base image without changing the Image tag, so that a merged base-image update can't silently publish nothing.
  9. As a maintainer, I want that failure to tell me exactly which change to the Pin to make, so that fixing a Renovate pull request is a one-line edit in review.
  10. As a maintainer, I want the same guard to catch my own hand-made base-image changes, so that I can't forget the Rebuild either.
  11. As a maintainer, I want the Rebuild number still raised by a person in review, so that ADR 0003's "raised by hand, visible in review" holds.
  12. As a Consumer, I want a Release on Forgejo for every published Image, so that I can see what each Image tag contains.
  13. As a Consumer, I want each Release named exactly like its Image tag (e.g. 3.2.0-r2), so that I can match a Release to the tag I pull without translating version numbers.
  14. As a Consumer, I want the Release to say which Upstream Version the Image builds and link Upstream's release notes, so that I know which MCP tools and fixes I get.
  15. As a Consumer, I want the Release to say whether the Upstream Version changed since the previous Release, so that I can tell an Upstream bump from a packaging Rebuild at a glance.
  16. As a Consumer, I want the Release to list the Consumer-relevant fixes and features since the previous Release, so that I know why a Rebuild happened (e.g. "built with Go 1.27, as Go 1.25 is out of support").
  17. As a Consumer, I want changes to this repo's internal tooling (scripts, agent skills, Renovate config, agent docs, CI) left out of the notes, so that the notes only contain what affects the Image.
  18. As a Consumer, I want an Upstream Version bump to show up in the Release even though Renovate commits it as a chore, so that the most important change is never missing.
  19. As a Consumer, I want the Release's git tag to point at the commit the Image was built from, so that it agrees with the Image's revision label.
  20. As a maintainer, I want CI to create the Release in the same job right after publishing, so that the Releases page can't drift from the registry.
  21. As a maintainer, I want the Release created only after the Image was pushed and checked, so that a Release never announces an Image that doesn't exist.
  22. As a maintainer, I want a push to main that doesn't change the Pin to create no Release, so that Releases match published Images one to one.
  23. As a maintainer, I want Release creation to be idempotent (create it if the current Image tag has no Release yet), so that re-running CI after a failed release step repairs the missing Release.
  24. As a maintainer, I want CI to create the Release through the Forgejo API without pushing to git, so that the job still never writes to the repository's branches.
  25. As a maintainer, I want no changelog file committed to main, so that releasing never needs a bot commit or a bot pull request.
  26. As a maintainer, I want the release job to use the run's automatic Actions token if it can create releases, so that no long-lived secret has to be added or rotated.
  27. As a maintainer, I want a documented fallback to a dedicated release token for the bot user, so that the setup still works if the automatic token can't create releases.
  28. As a maintainer, I want the previous Release found by git ancestry, so that r10 is never sorted before r2 and the notes always cover exactly what was merged since the last Image.
  29. As a maintainer, I want Releases backfilled for the Rebuilds published before the automation existed, so that the Releases page starts complete and the first automated notes don't contain the repo's whole history.
  30. As a maintainer, I want a dry run that prints the next Release's notes locally without creating anything, so that I can check the notes before merging.
  31. As a maintainer, I want CI to reject a pull request title that isn't a Conventional Commit, so that every squash commit on main can be read by the release notes.
  32. As a maintainer, I want the title check runnable locally with a given title, so that I can test it without a pull request.
  33. As a maintainer, I want the title check to re-run when I edit only the title, if Forgejo supports that, so that fixing a title doesn't need a new push.
  34. As Renovate, I want my Upstream bump pull requests to keep passing the title check, so that automated Pin bumps keep landing.
  35. As an agent implementing a later change, I want the Release concept in the glossary and the release decisions in an ADR, so that I don't reintroduce a changelog file, a repo version or semver sorting.
  36. As an agent, I want the release token gotcha and the internal-scope list documented in the agent docs, so that I know which scope keeps a commit out of the notes.

Implementation Decisions

Slice 1: Go 1.27 Rebuild, glossary and ADR (lands first, on its own)

  • The build stage moves from Go 1.25 to the 1.27-alpine Go image, pinned by its current index digest (Go 1.27.2 at the time of writing; look the digest up again when implementing). If the build or smoke test fails under 1.27, fall back to 1.26-alpine and say so in the pull request.
  • The Pin becomes Rebuild 2 of v3.2.0: the Rebuild's reference Upstream Version moves from v3.1.0 to v3.2.0 and the Rebuild number to 2, so the Image tag is 3.2.0-r2. The Upstream Version and commit don't change.
  • Commit and pull request title: fix: build the Image with Go 1.27, as Go 1.25 is out of support.
  • Glossary: add Release ("the record on Forgejo of one published Image, named by its Image tag, with the changes since the previous Release that matter to Consumers"; avoid: changelog, version, tag). Extend Rebuild to say each Rebuild gets exactly one Release.
  • New ADR 0005, "A Release mirrors each published Image". It records: Release equals Image tag; previous Release found by ancestry; CI creates it via the API after publishing, with no git push and no changelog file; git-cliff instead of release-it; the internal-scope filter; the header built from the Pin. It builds on ADR 0003 and doesn't replace it. It cites this issue.

Slice 2: Renovate tracks the base images

  • Turn on Renovate's Dockerfile manager next to the existing Pin manager. Group the Go build image and the distroless runtime base into one pull request, scheduled at most weekly. Allow digest and minor updates for the Go image.
  • The pull request notes tell the reviewer to raise the Rebuild in the Pin (per the Pin's header comment) before merging.
  • New CI guard, run on pull requests: if any base-image reference in the Dockerfile differs from the base branch while the Image tag from the Pin is unchanged, fail with a message naming the Pin edit to make. Changes to the Dockerfile that don't touch a base image don't trigger the guard.
  • Renovate does not raise the Rebuild itself (no post-upgrade tasks): that would need the bot's global server config and would contradict ADR 0003.

Slice 3: Releases

  • Release identity: one Release per published Image. Its name and git tag equal the Image tag (3.2.0-r2, no v prefix, so it never looks like an Upstream tag). The tag targets the commit the Image was built from.
  • Previous Release: the nearest earlier Release tag on the history of main (git ancestry), never semver ordering of tags.
  • Notes generator: git-cliff, run as a digest-pinned container image the way the existing linters are run. No Node toolchain enters the repo. (release-it was considered, ported from an earlier setup in another repo: here its version bump, commit and npm publish would all be disabled, and it has no built-in Forgejo release support, so it was rejected.)
  • Notes content: Conventional Commits groups for feat, fix, perf and breaking changes. Commits scoped scripts, skills, renovate, agents or ci are skipped as repo-internal. No scope (or image) means the change affects Consumers.
  • Header built from the Pin: the Upstream Version with a link to Upstream's release for it, the Rebuild number, and whether the Upstream Version changed since the previous Release. This covers Upstream bumps, which Renovate commits as chore(deps) and which the commit groups would otherwise hide. Renovate's commit style stays as it is.
  • Release script: a script in the style of the existing publish script. It computes the notes, then creates the Release with Forgejo's create-release endpoint, passing the tag name and the target commit, so Forgejo creates the tag itself. It has a dry-run mode (print the notes and the request payload, create nothing) and a post mode.
  • CI wiring: in the publish job, after the publish step succeeds, and only when publishing runs (push to or dispatch from main), create the Release if none exists yet for the current Image tag. This doesn't depend on whether this run pushed the Image, so a re-run repairs a missing Release and the publish script needs no new exit code. It runs in the existing queued publish concurrency group. The checkout keeps not persisting git credentials.
  • Token: try the run's automatic Actions token first. If it can't create releases, add a release-token secret for the existing bot user, scoped to repository write, with the bot given write access. Don't widen the registry token. Record the outcome as a one-line gotcha in the Forgejo agent doc.
  • Backfill: before the automation's first run, create Releases once for every Rebuild already published without one (3.2.0-r1, and 3.2.0-r2 if slice 1 published first). Each Release's tag targets the commit in that Image's revision label. The oldest one's notes run from the start of the history.
  • Title check: a CI step on pull requests checks the title against the Conventional Commits pattern: the repo's type list, an optional scope, an optional ! for breaking changes. It reads the title from the event, with no extra tool. Add the edited event type to the pull request trigger if Forgejo honours it; otherwise document that a title fix needs a new push.
  • Docs: the agent docs list the internal scopes and the rule that a scopeless or image-scoped change shows up in Release notes. The README's tag section points Consumers to the Releases page.

Testing Decisions

  • A good test checks behaviour a person can see: which commits appear in the notes, which SHA a tag targets, whether a check passes or fails and what it says. Nothing checks how the scripts are built internally.
  • All new behaviour is exposed as Makefile targets, the seam CI already drives:
    • make release-notes: a dry run of the next Release for the current Pin. Check it against real history: notes after 3.2.0-r1 must contain the Go 1.27 fix and leave out the scripts-scoped commits (#43, #44), and the header must name v3.2.0, Rebuild 2, and "Upstream Version unchanged".
    • The release script's post mode: its first real run is the backfill. Check that each tag targets the commit in its Image's revision label, and that running it again creates no duplicate.
    • make check-rebuild (base-image guard) and make check-title TITLE=… (title check), each runnable locally. Check that valid input passes and invalid input fails with the intended message.
  • Failure tests in CI follow the existing prior art: throwaway commits on the pull request that prove a check fails (as in the earlier "THROWAWAY break the Dockerfile" and "THROWAWAY Pin commit" commits, reverted afterwards). Here that means a base-image change without a Rebuild, and a non-conventional title.
  • The Go 1.27 slice is verified by the existing gates: lint, Pin verification, the multi-arch build, and the smoke test of both architectures in CI.
  • The automatic-token question is answered by one dispatch on main after slice 3 lands, checked against the Releases page.
  • No shell test framework (e.g. bats) is introduced; the scripts are small enough for the targets above.

Out of Scope

  • A version for this repo or the Image independent of the Upstream Version: ADR 0003's tag scheme stays. Replacing it would need its own ticket, a superseding ADR and a migration plan for Consumers on :3.
  • A CHANGELOG.md file, or any bot commit or pull request to main.
  • release-it, Node, and Renovate's npm manager.
  • Renovate raising the Rebuild automatically (post-upgrade tasks, global bot config).
  • Linting individual commits (commitlint, commit hooks): with squash merges only the title reaches main.
  • Copying Upstream's release notes into Releases: the Release links them.
  • Branch protection changes.
  • Updating the distroless base beyond its current digest in slice 1 (it is already current).

Further Notes

  • Slice order: slice 1 can land on its own right away, since it's a security fix. Slices 2 and 3 are independent of each other. The backfill in slice 3 must run before the automation's first real Release.
  • Upstream v3.2.0 requires only Go 1.25.5, so a newer toolchain builds it unchanged.
  • As semver, 3.2.0-r2 is a prerelease and prerelease parts compare as text. That's why the previous Release is found by ancestry and why the publish script compares Rebuilds as number arrays.
  • Earlier history has non-squash merge commits ("Merge pull request …"); git-cliff skips them as non-conventional while the conventional commits inside them still count. Check this against the backfill notes.
## Problem Statement The Image is a static Go binary, so Go's standard library (TLS, HTTP, …) ships inside it. Its build stage still uses Go 1.25, which is out of support (the supported releases are 1.27 and 1.26), so every Image we publish carries a standard library that no longer gets security fixes. Nobody noticed because Renovate only watches the Pin, not the base images the Image is built on. Consumers also have no way to learn what changed when a new Image appears. The registry gains an `X.Y.Z-rN` tag and the moving tags (`3.2.0`, `3.2`, `3`, `latest`) move, but there is no record of why: whether Upstream moved to a new Upstream Version, or a Rebuild picked up a toolchain or base-image fix. The commit history uses Conventional Commits, but nothing turns it into release notes, and nothing checks that a pull request's title, which becomes the squash commit on main, follows the convention. ## Solution 1. Rebuild the Image with Go 1.27, as Rebuild 2 of Upstream Version v3.2.0 (Image tag `3.2.0-r2`). 2. Renovate proposes base-image updates (the Go build image and the distroless runtime base) once a week in one grouped pull request. A CI guard makes sure such a change, or any hand-made change to a base image, raises the Rebuild in the same pull request, so it actually gets published. 3. Every published Image gets a **Release** on Forgejo, named exactly like its Image tag. CI creates it right after publishing. Its notes state which Upstream Version the Image builds (linking Upstream's own release notes), the Rebuild number, whether the Upstream Version changed, and the Consumer-relevant `feat`/`fix`/`perf`/breaking commits since the previous Release. 4. CI rejects pull request titles that aren't Conventional Commits, since the title is what the release notes read. The tag scheme of ADR 0003 stays as it is: the Image has no version of its own besides the Upstream Version plus the Rebuild number. ## User Stories 1. As a Consumer, I want the Image built with a supported Go toolchain, so that the TLS and HTTP code inside the binary still gets security fixes. 2. As a Consumer on `:3`, I want the Go 1.27 Image to reach me by a normal pull, so that I get the fix without changing my configuration. 3. As a Consumer pinned to an exact Rebuild, I want `3.2.0-r2` to exist as a new immutable tag, so that `3.2.0-r1` stays exactly what it was. 4. As a maintainer, I want Renovate to propose updates to the Go build image, so that the toolchain never silently falls out of support again. 5. As a maintainer, I want Renovate to propose updates to the distroless runtime base, so that the runtime layer stays current too. 6. As a maintainer, I want minor Go updates (1.27 → 1.28) proposed alongside digest updates, so that I'm moved to new Go releases before the old ones go out of support. 7. As a maintainer, I want all base-image updates grouped into one pull request at most once a week, so that each round of updates costs one Rebuild and one Release instead of several. 8. As a maintainer, I want CI to fail a pull request that changes a base image without changing the Image tag, so that a merged base-image update can't silently publish nothing. 9. As a maintainer, I want that failure to tell me exactly which change to the Pin to make, so that fixing a Renovate pull request is a one-line edit in review. 10. As a maintainer, I want the same guard to catch my own hand-made base-image changes, so that I can't forget the Rebuild either. 11. As a maintainer, I want the Rebuild number still raised by a person in review, so that ADR 0003's "raised by hand, visible in review" holds. 12. As a Consumer, I want a Release on Forgejo for every published Image, so that I can see what each Image tag contains. 13. As a Consumer, I want each Release named exactly like its Image tag (e.g. `3.2.0-r2`), so that I can match a Release to the tag I pull without translating version numbers. 14. As a Consumer, I want the Release to say which Upstream Version the Image builds and link Upstream's release notes, so that I know which MCP tools and fixes I get. 15. As a Consumer, I want the Release to say whether the Upstream Version changed since the previous Release, so that I can tell an Upstream bump from a packaging Rebuild at a glance. 16. As a Consumer, I want the Release to list the Consumer-relevant fixes and features since the previous Release, so that I know why a Rebuild happened (e.g. "built with Go 1.27, as Go 1.25 is out of support"). 17. As a Consumer, I want changes to this repo's internal tooling (scripts, agent skills, Renovate config, agent docs, CI) left out of the notes, so that the notes only contain what affects the Image. 18. As a Consumer, I want an Upstream Version bump to show up in the Release even though Renovate commits it as a chore, so that the most important change is never missing. 19. As a Consumer, I want the Release's git tag to point at the commit the Image was built from, so that it agrees with the Image's revision label. 20. As a maintainer, I want CI to create the Release in the same job right after publishing, so that the Releases page can't drift from the registry. 21. As a maintainer, I want the Release created only after the Image was pushed and checked, so that a Release never announces an Image that doesn't exist. 22. As a maintainer, I want a push to main that doesn't change the Pin to create no Release, so that Releases match published Images one to one. 23. As a maintainer, I want Release creation to be idempotent (create it if the current Image tag has no Release yet), so that re-running CI after a failed release step repairs the missing Release. 24. As a maintainer, I want CI to create the Release through the Forgejo API without pushing to git, so that the job still never writes to the repository's branches. 25. As a maintainer, I want no changelog file committed to main, so that releasing never needs a bot commit or a bot pull request. 26. As a maintainer, I want the release job to use the run's automatic Actions token if it can create releases, so that no long-lived secret has to be added or rotated. 27. As a maintainer, I want a documented fallback to a dedicated release token for the bot user, so that the setup still works if the automatic token can't create releases. 28. As a maintainer, I want the previous Release found by git ancestry, so that `r10` is never sorted before `r2` and the notes always cover exactly what was merged since the last Image. 29. As a maintainer, I want Releases backfilled for the Rebuilds published before the automation existed, so that the Releases page starts complete and the first automated notes don't contain the repo's whole history. 30. As a maintainer, I want a dry run that prints the next Release's notes locally without creating anything, so that I can check the notes before merging. 31. As a maintainer, I want CI to reject a pull request title that isn't a Conventional Commit, so that every squash commit on main can be read by the release notes. 32. As a maintainer, I want the title check runnable locally with a given title, so that I can test it without a pull request. 33. As a maintainer, I want the title check to re-run when I edit only the title, if Forgejo supports that, so that fixing a title doesn't need a new push. 34. As Renovate, I want my Upstream bump pull requests to keep passing the title check, so that automated Pin bumps keep landing. 35. As an agent implementing a later change, I want the Release concept in the glossary and the release decisions in an ADR, so that I don't reintroduce a changelog file, a repo version or semver sorting. 36. As an agent, I want the release token gotcha and the internal-scope list documented in the agent docs, so that I know which scope keeps a commit out of the notes. ## Implementation Decisions **Slice 1: Go 1.27 Rebuild, glossary and ADR (lands first, on its own)** - The build stage moves from Go 1.25 to the `1.27-alpine` Go image, pinned by its current index digest (Go 1.27.2 at the time of writing; look the digest up again when implementing). If the build or smoke test fails under 1.27, fall back to `1.26-alpine` and say so in the pull request. - The Pin becomes Rebuild 2 of v3.2.0: the Rebuild's reference Upstream Version moves from v3.1.0 to v3.2.0 and the Rebuild number to 2, so the Image tag is `3.2.0-r2`. The Upstream Version and commit don't change. - Commit and pull request title: `fix: build the Image with Go 1.27, as Go 1.25 is out of support`. - Glossary: add **Release** ("the record on Forgejo of one published Image, named by its Image tag, with the changes since the previous Release that matter to Consumers"; avoid: changelog, version, tag). Extend **Rebuild** to say each Rebuild gets exactly one Release. - New ADR 0005, "A Release mirrors each published Image". It records: Release equals Image tag; previous Release found by ancestry; CI creates it via the API after publishing, with no git push and no changelog file; git-cliff instead of release-it; the internal-scope filter; the header built from the Pin. It builds on ADR 0003 and doesn't replace it. It cites this issue. **Slice 2: Renovate tracks the base images** - Turn on Renovate's Dockerfile manager next to the existing Pin manager. Group the Go build image and the distroless runtime base into one pull request, scheduled at most weekly. Allow digest and minor updates for the Go image. - The pull request notes tell the reviewer to raise the Rebuild in the Pin (per the Pin's header comment) before merging. - New CI guard, run on pull requests: if any base-image reference in the Dockerfile differs from the base branch while the Image tag from the Pin is unchanged, fail with a message naming the Pin edit to make. Changes to the Dockerfile that don't touch a base image don't trigger the guard. - Renovate does not raise the Rebuild itself (no post-upgrade tasks): that would need the bot's global server config and would contradict ADR 0003. **Slice 3: Releases** - **Release identity:** one Release per published Image. Its name and git tag equal the Image tag (`3.2.0-r2`, no `v` prefix, so it never looks like an Upstream tag). The tag targets the commit the Image was built from. - **Previous Release:** the nearest earlier Release tag on the history of main (git ancestry), never semver ordering of tags. - **Notes generator:** git-cliff, run as a digest-pinned container image the way the existing linters are run. No Node toolchain enters the repo. (release-it was considered, ported from an earlier setup in another repo: here its version bump, commit and npm publish would all be disabled, and it has no built-in Forgejo release support, so it was rejected.) - **Notes content:** Conventional Commits groups for `feat`, `fix`, `perf` and breaking changes. Commits scoped `scripts`, `skills`, `renovate`, `agents` or `ci` are skipped as repo-internal. No scope (or `image`) means the change affects Consumers. - **Header built from the Pin:** the Upstream Version with a link to Upstream's release for it, the Rebuild number, and whether the Upstream Version changed since the previous Release. This covers Upstream bumps, which Renovate commits as `chore(deps)` and which the commit groups would otherwise hide. Renovate's commit style stays as it is. - **Release script:** a script in the style of the existing publish script. It computes the notes, then creates the Release with Forgejo's create-release endpoint, passing the tag name and the target commit, so Forgejo creates the tag itself. It has a dry-run mode (print the notes and the request payload, create nothing) and a post mode. - **CI wiring:** in the publish job, after the publish step succeeds, and only when publishing runs (push to or dispatch from main), create the Release if none exists yet for the current Image tag. This doesn't depend on whether this run pushed the Image, so a re-run repairs a missing Release and the publish script needs no new exit code. It runs in the existing queued publish concurrency group. The checkout keeps not persisting git credentials. - **Token:** try the run's automatic Actions token first. If it can't create releases, add a release-token secret for the existing bot user, scoped to repository write, with the bot given write access. Don't widen the registry token. Record the outcome as a one-line gotcha in the Forgejo agent doc. - **Backfill:** before the automation's first run, create Releases once for every Rebuild already published without one (`3.2.0-r1`, and `3.2.0-r2` if slice 1 published first). Each Release's tag targets the commit in that Image's revision label. The oldest one's notes run from the start of the history. - **Title check:** a CI step on pull requests checks the title against the Conventional Commits pattern: the repo's type list, an optional scope, an optional `!` for breaking changes. It reads the title from the event, with no extra tool. Add the edited event type to the pull request trigger if Forgejo honours it; otherwise document that a title fix needs a new push. - **Docs:** the agent docs list the internal scopes and the rule that a scopeless or `image`-scoped change shows up in Release notes. The README's tag section points Consumers to the Releases page. ## Testing Decisions - A good test checks behaviour a person can see: which commits appear in the notes, which SHA a tag targets, whether a check passes or fails and what it says. Nothing checks how the scripts are built internally. - All new behaviour is exposed as Makefile targets, the seam CI already drives: - `make release-notes`: a dry run of the next Release for the current Pin. Check it against real history: notes after `3.2.0-r1` must contain the Go 1.27 fix and leave out the `scripts`-scoped commits (#43, #44), and the header must name v3.2.0, Rebuild 2, and "Upstream Version unchanged". - The release script's post mode: its first real run is the backfill. Check that each tag targets the commit in its Image's revision label, and that running it again creates no duplicate. - `make check-rebuild` (base-image guard) and `make check-title TITLE=…` (title check), each runnable locally. Check that valid input passes and invalid input fails with the intended message. - Failure tests in CI follow the existing prior art: throwaway commits on the pull request that prove a check fails (as in the earlier "THROWAWAY break the Dockerfile" and "THROWAWAY Pin commit" commits, reverted afterwards). Here that means a base-image change without a Rebuild, and a non-conventional title. - The Go 1.27 slice is verified by the existing gates: lint, Pin verification, the multi-arch build, and the smoke test of both architectures in CI. - The automatic-token question is answered by one dispatch on main after slice 3 lands, checked against the Releases page. - No shell test framework (e.g. bats) is introduced; the scripts are small enough for the targets above. ## Out of Scope - A version for this repo or the Image independent of the Upstream Version: ADR 0003's tag scheme stays. Replacing it would need its own ticket, a superseding ADR and a migration plan for Consumers on `:3`. - A `CHANGELOG.md` file, or any bot commit or pull request to main. - release-it, Node, and Renovate's npm manager. - Renovate raising the Rebuild automatically (post-upgrade tasks, global bot config). - Linting individual commits (commitlint, commit hooks): with squash merges only the title reaches main. - Copying Upstream's release notes into Releases: the Release links them. - Branch protection changes. - Updating the distroless base beyond its current digest in slice 1 (it is already current). ## Further Notes - Slice order: slice 1 can land on its own right away, since it's a security fix. Slices 2 and 3 are independent of each other. The backfill in slice 3 must run before the automation's first real Release. - Upstream v3.2.0 requires only Go 1.25.5, so a newer toolchain builds it unchanged. - As semver, `3.2.0-r2` is a prerelease and prerelease parts compare as text. That's why the previous Release is found by ancestry and why the publish script compares Rebuilds as number arrays. - Earlier history has non-squash merge commits ("Merge pull request …"); git-cliff skips them as non-conventional while the conventional commits inside them still count. Check this against the backfill notes.
Author
Owner

Delivered through #53, #54 and #55; tickets #46–#52 are closed.

Solution

  1. Go 1.27 Rebuild (#46, #53): built with Go 1.27.2, the Pin is Rebuild 2 of v3.2.0, and 3.2.0-r2 is published with the moving tags on it. The glossary defines Release, and ADR 0005 records the release decisions.
  2. Base images (#47, #50): Renovate proposes the Go build image and the distroless base in one weekly PR, fix(deps): update base images (digest + minor for Go, no majors), whose notes ask to raise the Rebuild. make check-rebuild fails a PR that changes a base image (FROM, # syntax=, external COPY --from / RUN --mount=from=) without a new Image tag, and names the Pin edit. Shown failing in CI with a throwaway commit (run 6162), reverted.
  3. Releases (#48, #51, #52): make release-notes previews the next Release; make release creates it if missing and fails if an existing Release's tag is on another commit. git-cliff (digest-pinned) skips the internal scopes scripts, skills, renovate, agents, ci; the header comes from the Pin; the previous Release is found by ancestry. CI creates the Release right after publishing, with the automatic Actions token (no secret needed).
    • 3.2.0-r1 on 7f2e214: backfilled.
    • 3.2.0-r2 on 6c4b187: created by CI run 6177. The internal #31 line was removed from its notes by hand.
    • Run 6181 (push without a Pin change) created nothing.
  4. PR titles (#49): make check-title runs in CI, and a title-only edit re-runs it (run 6164 failed on a bad title, 6165 passed after restoring it).

Differences from the spec

  • Two PRs instead of one: #53 shipped the security fix on its own; #55 recorded the token outcome in docs/agents/forgejo.md.
  • Base-image rounds are committed as fix(deps), not chore(deps), so their Release says why the Rebuild happened.
  • Added beyond the spec: make test (a plain bash script with a local API stub) and a make release-notes dry run on every PR, both in CI.
  • The backfill needed only 3.2.0-r1, the only Image published before the automation.

Open

  • An unlisted scope or no scope counts as Consumer-facing, as #31's did: give internal changes an internal scope.
Delivered through #53, #54 and #55; tickets #46–#52 are closed. ## Solution 1. **Go 1.27 Rebuild** (#46, #53): built with Go 1.27.2, the Pin is Rebuild 2 of v3.2.0, and `3.2.0-r2` is published with the moving tags on it. The glossary defines **Release**, and ADR 0005 records the release decisions. 2. **Base images** (#47, #50): Renovate proposes the Go build image and the distroless base in one weekly PR, `fix(deps): update base images` (digest + minor for Go, no majors), whose notes ask to raise the Rebuild. `make check-rebuild` fails a PR that changes a base image (`FROM`, `# syntax=`, external `COPY --from` / `RUN --mount=from=`) without a new Image tag, and names the Pin edit. Shown failing in CI with a throwaway commit (run 6162), reverted. 3. **Releases** (#48, #51, #52): `make release-notes` previews the next Release; `make release` creates it if missing and fails if an existing Release's tag is on another commit. git-cliff (digest-pinned) skips the internal scopes `scripts`, `skills`, `renovate`, `agents`, `ci`; the header comes from the Pin; the previous Release is found by ancestry. CI creates the Release right after publishing, with the automatic Actions token (no secret needed). - [`3.2.0-r1`](https://code.vicoli.de/vicoli-oss/docker-forgejo-mcp/releases/tag/3.2.0-r1) on `7f2e214`: backfilled. - [`3.2.0-r2`](https://code.vicoli.de/vicoli-oss/docker-forgejo-mcp/releases/tag/3.2.0-r2) on `6c4b187`: created by CI run 6177. The internal #31 line was removed from its notes by hand. - Run 6181 (push without a Pin change) created nothing. 4. **PR titles** (#49): `make check-title` runs in CI, and a title-only edit re-runs it (run 6164 failed on a bad title, 6165 passed after restoring it). ## Differences from the spec - Two PRs instead of one: #53 shipped the security fix on its own; #55 recorded the token outcome in `docs/agents/forgejo.md`. - Base-image rounds are committed as `fix(deps)`, not `chore(deps)`, so their Release says why the Rebuild happened. - Added beyond the spec: `make test` (a plain bash script with a local API stub) and a `make release-notes` dry run on every PR, both in CI. - The backfill needed only `3.2.0-r1`, the only Image published before the automation. ## Open - An unlisted scope or no scope counts as Consumer-facing, as #31's did: give internal changes an internal scope.
piscis 2026-10-10 14:49:37 +00:00
  • closed this issue
  • added the
    spec
    label
Sign in to join this conversation.
No description provided.