Skip to content

fix(release): release assets and notes inconsistent; pipeline incompatible with immutable releases #222

Description

@tarotene

Problem

GitHub Releases v0.1.0–v0.2.2 have inconsistent assets and release notes:

Release immutable Notes Assets
v0.1.0 false Empty 0 (pipeline not yet added)
v0.2.0 false Correct 4 ✅
v0.2.1 true Minimal (truncated) 0
v0.2.2 true Broken header + wrong commits 0

Root causes

  1. Structural incompatibility (critical): release-binaries.yml uploads assets via
    gh release upload after the release is published (release: published trigger).
    With immutable releases enabled, published = immediately locked → HTTP 422 on every
    upload attempt. This means no future release will ever get binaries without a fix.

  2. v0.2.1 trigger gap: The release event from GITHUB_TOKEN-authenticated API calls
    is suppressed by GitHub's anti-recursion guard. The App token migration (ci(release-plz): migrate to GitHub App token so release PR CI and release-binaries both fire #206) fixed
    the forward path, but v0.2.1 was already published (immutable).

  3. Changelog template bug: release-plz.toml [changelog] body generates a broken
    Markdown header ## [0.2.2]([`0.2.2`](url)) (backtick code spans inside a link
    break the Markdown). v0.2.2 also contains wrong commits (pre-v0.1.0 entries from an
    unconstrained git range).

Fix scope (one PR)

  • Pipeline: Convert release-binaries.yml to workflow_call + workflow_dispatch
    (remove release: published). Add publish job: gh release edit --draft=false after
    all builds succeed.
  • release-plz.toml: Add git_release_draft = true to telepath-wire package so
    release-plz creates a draft release. The release-binaries job attaches binaries to
    the draft, then publishes it (draft→publish before immutable lock).
  • release-plz.yml: Add release-binaries job after release-plz-release; pass the
    resolved tag via workflow_call.
  • Changelog template: Fix broken Markdown header and clean up CHANGELOG.md for
    v0.2.1/v0.2.2 with correct commit ranges.
  • Docs: Update AGENTS.md and docs/releasing.md to reflect the draft→publish flow
    and recovery procedures.

Backfill (post-merge ops — tracked in this issue)

  • v0.1.0: attach 4 binaries + add release notes (gh workflow run release-binaries.yml -f tag=v0.1.0)
  • v0.2.0: fix "5 platforms" → "4 platforms" in release notes
  • v0.2.1: update release notes to correct commit list + add disclaimer (immutable; assets cannot be attached)
  • v0.2.2: update release notes to correct commit list + add disclaimer (immutable; assets cannot be attached)

Immutable releases — key constraint

Disabling immutable releases does not retroactively unlock already-immutable releases.
v0.2.1 and v0.2.2 are permanently immutable; their assets cannot be added even if the
repo setting is toggled. Only title and release notes can be edited.

Source: https://docs.github.com/en/code-security/concepts/supply-chain-security/immutable-releases

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingciCI/CD configurationreleaseRelease engineering & versioning

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions