Skip to content

release: unify all channel-tag moves onto the gh-api/App-token path (root fix for dev-lead orphan-tag spam) #1076

Closed

Description

@don-petry

Re-scoped (supersedes the idempotency-only framing)

The original #1076 proposed making autocut idempotent (reuse an existing release tag instead of bumping) to stop orphan-tag spam. That treats the symptom. The root cause is that the dev-lead/next channel-tag move fails — so the candidate never converges and, on each retry, a new orphaned dev-lead/vX.Y.Z is minted.

Root cause

cut-release.sh and canary-rollout.sh each had a split move path:

Path Agents Credential vs release-channel-tags ruleset
gh api PATCH cross-repo (#482) App token bypass honored → works
local git push --force this-repo (dev-lead) checkout App token GH013 on the update rule

The ruleset (17432201) restricts update+deletion on refs/tags/dev-lead/** + refs/tags/pr-review/**, with the release-manager App (4193127, bypass_mode=always) as a bypass actor. Tag creates are unrestricted (so dev-lead/v1.5.2 pushed), but a channel force-update via local git push is not granted the App's bypass and 013s — while the same App token via gh api is honored. Evidence: scheduled run 28707434935 — [new tag] dev-lead/v1.5.2 succeeded, dev-lead/next push [remote rejected] … Cannot update this protected ref.

Fix (this issue)

Route every tag operation — resolve, create, channel-move, promote, rollback — through gh api against the agent's host repo, for this-repo and cross-repo agents alike. One consistent path; the App-token bypass applies uniformly. Also migration-robust: correctness stops depending on which repo the workflow runs in (after the .github relocation the 6 .github agents flip to the this-repo path and dev-lead to cross-repo — both keep working).

  • cut-release.sh: single gh-api path; this_repo/agent_host_repo helpers resolve the host; local git-tag/push branch + git-identity source removed.
  • canary-rollout.sh: cmd_promote + cmd_rollback move via _gh_move_tag on the host for all agents (host defaults to THIS_REPO).
  • Idempotent reuse (the original release: unify all channel-tag moves onto the gh-api/App-token path (root fix for dev-lead orphan-tag spam) #1076 idea) is retained as defense-in-depth value but is no longer the crux — with reliable moves there is nothing to spam.
  • Tests: consistent-path invariant + agent_host_repo coverage; this-repo cut/promote assert the gh-api move; structural guards fail if a local git tag/push returns. 130/130 bats pass.

Config caveat (cannot self-apply)

Closing this fully assumes the App bypass is honored via gh api on .github-private's ruleset (it is a bypass actor, mode=always). If a channel move still 013s via the API, the bypass list itself needs correcting — a ruleset change, surfaced to a maintainer, not workaroundable in code.

Implemented in PR (below).

Activity

  1. github-actions commented on Jul 4, 2026

    @github-actions
    Contributor

    Thanks for the thorough write-up and for including the observed live behavior, acceptance criteria, and related issue refs — this is a very well-scoped report. Since you've already identified the fix path (checking for an existing release tag at the target commit before cutting), can you confirm whether the cut-release.sh --promote path handles the case where next is already on the correct tag (i.e., is the move already idempotent, or does that also need guarding)?

  2. don-petry commented on Jul 4, 2026

    @don-petry
    CollaboratorAuthor

    Dev-Lead Implementation Plan

    Issue: #1076 — autocut: make the cut idempotent — reuse an existing release tag at the target commit instead of bumping (prevents orphan-tag spam on a blocked next-move)

    Scope

    Make canary-rollout.sh autocut idempotent on the target commit: when a <agent>/vX.Y.Z release tag already points at the host main HEAD, reuse it (move next via cut-release.sh --promote) instead of minting a new bumped version — eliminating orphan-tag spam on a partial-failure retry where the cut succeeded but the next move was blocked.

    Implementation Checklist

    • scripts/canary-rollout.sh — add _host_release_version_at_commit <agent> <commit> helper (resolve, via the API, the existing <agent>/vX.Y.Z whose dereferenced commit equals the target commit; empty if none)
    • scripts/canary-rollout.sh — in _autocut_agent, before computing the bump, branch: if a release tag already points at mainsha, invoke cut-release.sh <agent> <existing> --channel next --promote --push (no new cut); otherwise cut the bumped version as today
    • Honor --dry-run on the reuse branch (print the intended --promote without invoking cut-release)

    Tests to Write

    • tests/canary_rollout.bats — extend _autocut_stub to map a release version's tag to the target commit
    • existing tag at target commit + next not on it → autocut moves next via --promote, cuts NO new version
    • no tag at the target commit → cuts the bumped version as today (existing behavior preserved)
    • partial-failure retry (cut already at main HEAD) cuts no duplicate version
    • reuse branch honors --dry-run

    Test Command

    bash scripts/run-bats.sh tests/canary_rollout.bats (full suite: bash .dev-lead/scripts/dev-lead-lint.sh + all bats)

  3. don-petry commented on Jul 4, 2026

    @don-petry
    CollaboratorAuthor

    Dev-Lead: Implementation Complete

    Plan Execution

    • Added _host_release_version_at_commit <agent> <commit> helper to scripts/canary-rollout.sh (resolves, via the API, the existing <agent>/vX.Y.Z whose dereferenced commit equals the target commit — dereferencing annotated tags, mirroring _gh_candidate_cut_date; empty if none)
    • Added the idempotent-reuse branch in _autocut_agent: when a release tag already points at the target commit (main HEAD), it moves next onto it via cut-release.sh <agent> <existing> --channel next --promote --push and cuts NO new version
    • Reuse branch honors --dry-run (prints the intended --promote without invoking cut-release)
    • Extended _autocut_stub in tests/canary_rollout.bats to map a release version's tag to the target commit (TSV for the release-at-commit lookup; plain refs for the highest-version bump)
    • Added 4 bats cases (reuse / retry-no-duplicate / bump-preserved / dry-run)

    Test Results

    ok 69 orchestrator: autocut is a no-op when CANARY_AUTO_CUT is not 'true' (kill-switch off)
    ok 70 orchestrator: autocut cuts a patch-bumped version + moves next when the reusable blob differs on main
    ok 71 orchestrator: autocut is idempotent — identical blob on main and next is a clean no-op
    ok 72 orchestrator: autocut --dry-run prints the intended cut without invoking cut-release --push
    ok 73 orchestrator: autocut honors the registry autocut.bump override (minor)
    ok 74 orchestrator: autocut is cross-repo aware — cuts v2.1.1 for auto-rebase from the host main HEAD (#1069)
    ok 75 orchestrator: autocut reuses an existing release tag at main HEAD, moving next via --promote (no new cut) (#1076)
    ok 76 orchestrator: autocut retry-after-partial-failure cuts no duplicate version (#1076)
    ok 77 orchestrator: autocut still cuts a bumped version when NO release tag points at main HEAD (#1076)
    ok 78 orchestrator: autocut --dry-run on the reuse path prints the --promote without invoking cut-release (#1076)
    
    • Full tests/canary_rollout.bats: 78/78 pass. Entire repo bats suite: 0 files with failures.
    • bash .dev-lead/scripts/dev-lead-lint.sh: all checks passed (shellcheck on 88 files + agent-profile + CODEOWNERS validation).
    • shellcheck -S warning on the changed scripts: clean.

    Files Changed

    • scripts/canary-rollout.sh: new _host_release_version_at_commit helper + idempotent-reuse branch in _autocut_agent.
    • tests/canary_rollout.bats: _autocut_stub extended with a release_at_main param; 4 new #1076 test cases.

    Acceptance mapping

    • Existing <agent>/vX.Y.Z at target commit and next not on it → autocut moves next to it, cuts nothing new → test 75.
    • No tag at the target commit → cuts the bumped version as today → test 77 (behavior preserved).
    • bats for both; a partial-failure retry cuts no duplicate version → tests 75/76/77/78.

    Notes

    • Detection reuses the existing cut-release.sh --promote primitive (feat: wire cut-release.sh cross-repo publish via gh api (#872) #959/feat(cut-release): add --promote for ring-to-ring channel moves (#501) #992) rather than adding a new tag-move path, keeping immutability and the ruleset-boundary behavior unchanged.
    • Reuse resolution is best-effort: any API gap yields empty and falls through to the today (bump) path — consistent with autocut's existing best-effort posture.
    • Cross-repo agents were already idempotent (their next moves succeed); this fix targets the blocked-move case (observed live on dev-lead, whose next move is blocked by the .github-private release-channel-tags ruleset — the ruleset bypass is a separate fix).
  4. changed the title [-]autocut: make the cut idempotent — reuse an existing release tag at the target commit instead of bumping (prevents orphan-tag spam on a blocked next-move)[/-] [+]release: unify all channel-tag moves onto the gh-api/App-token path (root fix for dev-lead orphan-tag spam)[/+] on Jul 4, 2026
  5. added 18 commits that reference this issue on Aug 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugBug reportsdev-leadFor dev-lead agent pickupenhancementFeature requests

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions