Managing Archestra Releases

Always read platform/dev/RELEASE.md first. It is the authoritative release checklist. Do not assume release/1.3 is always the active branch. Check current branches, tags, and settings before acting.

This is an execution skill, not only a guide. Use git, gh, and the GitHub API to complete every applicable step, create the configuration PRs, monitor them through the merge queue, and verify the resulting state. Do not hand routine steps back to the operator.

Publication Paths

• Beta (main): Merging a release PR on main automatically publishes a beta release. It moves only archestra/platform:latest; companion and agent images keep latest on the stable line.
• Stable (release/X.Y): Merging a release PR on release/X.Y builds stable artifacts. After all builds succeed, the workflow automatically publishes the release and updates the companion and agent images' latest. It moves archestra/platform:latest only when no newer release is published.

Neither release channel uses a GitHub environment. Merging a release PR authorizes automatic publication after successful builds; finish qualification before that merge. Starting a new stable branch adds configuration steps and uses the same stable publication pipeline.

Backporting Fixes

1. Land fixes on main first. Fixes on main ship automatically in the next beta release.
2. Read .github/backport-targets.json and apply backport release/X.Y labels to the source PR for the configured targets. Labels work before or after merge. Open Backport PRs creates separate cherry-pick -x PRs; it never merges a release PR or starts publication.
3. Monitor the resulting backport PRs and their checks — including the cross-track migration compatibility check and the released-tag upgrade replay. Review the release-specific diff before queueing them under the user's merge authorization.
4. On conflicts, use the manual cherry-pick -x procedure in platform/dev/RELEASE.md. Include only necessary fixes; no features, refactors, or schema changes. Never merge main into release or candidate branches. A migration backport is only permissible under the prefix rule in platform/dev/RELEASE.md (the stable branch's migration history must remain a prefix of main's, matched by SQL content); forward repairs on main recover already-shipped gaps and are never a planned backport path.
5. Retry API failures through Open Backport PRs workflow dispatch. Existing PRs are not duplicated or reopened, and existing branches are not overwritten. Investigate an unexpected existing branch instead of deleting it.
6. During stable cutover, update the configured targets and their labels to include the new branch and remove the retired line. The automation's source of truth is the default branch.

Cutting A New Stable Line End To End

Derive X.Y, the previous stable line, and the next beta line from live branches, tags, releases, and Release Please manifests. Never substitute a remembered version.

1. Preflight And Stable-Cut Approval

1. Fetch branches and tags. Confirm the selected platform-vX.Y.0-beta.N is a published prerelease, points to a commit on main, and passed the agreed qualification.
2. Reconcile, rather than overwrite, any existing release/X.Y, platform-vX.Y.0, draft release, release PR, exact queue ruleset, or candidate workflow. Fetch every relevant ref and read the release, PR, workflow, and ruleset state. Resume only when each existing object belongs to this selected beta commit and the recorded stage has all of its required protections and artifacts; never recreate an existing branch, tag, release, or PR. A missing, stale, or contradictory object is a recovery stop, not a reason to delete or replace it.
3. Confirm releases are not frozen, the current stable release is older than X.Y.0, and no previous-line release workflow is running, queued, or waiting for approval. A busy or stale previous-line candidate must be resolved under the recovery rules before a new cut can proceed.
4. Inspect the live release/* core ruleset and the exact-branch merge-queue ruleset for the active stable line. Fail closed if they cannot be read. Before a new branch is created, the core ruleset must be active and have its normal do_not_enforce_on_create value; an unexpected pre-existing exemption is ruleset drift and must not be reset without its saved original payload.
5. Present one approval containing the beta tag, new stable version and branch, previous line that will become EOL, planned repository-setting changes, the detected resume stage (if any), and the PRs that will be created and merged. Do not create the branch, modify settings, or merge a release PR until the operator explicitly authorizes this stable cut.

That authorization covers the mechanical preparation, release-PR merge, and automatic publication described below. There is no independent post-build deployment approval.

2. Create And Protect The Branch

1. Inspect do_not_enforce_on_create in the release/* core ruleset's required checks. If it is false and the release automation's bypass identity cannot create the branch, update only that field to true under the stable-cut authorization. Preserve the complete original ruleset payload for restoration and arrange cleanup before making the update.
2. Create release/X.Y at the exact verified beta tag and push it. Never create it from main. Restore the original core ruleset and read it back whether creation succeeds, fails, or the process is interrupted; do not leave branch creation exempted. If creation or restoration fails, stop after the readback. Do not create the queue ruleset or any PR until restoration is verified.
3. Confirm the repository's active release/* core ruleset applies to the new branch and matches main for pull requests, required checks, deletion, non-fast-forward protection, and bypass actors.
4. Before any PR can merge, create an exact-branch merge-queue ruleset for release/X.Y. GitHub rejects merge queues on wildcard rulesets. Clone the live active stable line's queue rule and bypass actors through the rulesets API, changing only its name and included ref. Read the created ruleset back and compare its queue parameters with main.

Do not hard-code ruleset IDs, check names, integration IDs, or queue parameters in the skill. Discover and clone current settings so future changes on main are preserved. If no unambiguous current setting can be derived, include that choice in the stable-cut approval instead of guessing.

3. Prepare And Cut X.Y.0

1. Branch from release/X.Y and change packages.platform in .github/release-please/release-please-config.json to:
   • versioning: always-bump-patch
   • prerelease: false
   • remove prerelease-type
   • temporary release-as: X.Y.0
   • draft: true
2. Open the release-configuration PR against release/X.Y, monitor its required checks, and merge it through the new queue.
3. Inventory open PRs against the previous stable line. Recreate every still-required fix that already landed on main as a cherry-pick -x backport to release/X.Y and merge it before the initial release. Wait for Release Please to update the release PR.
4. Wait for Release Please to create or update the X.Y.0 PR. Verify its base, manifest version, changelog, release configuration, and required checks. Finish qualification before merging; the release workflow publishes automatically.
5. Complete the old-line retirement below before merging the release PR. The selected beta and backported fixes must already have passed qualification.

4. Commit The Cutover And Publish

Only continue after the selected beta and any backported fixes pass qualification and the release PR is ready. The old line stays supported until this point.

1. Confirm no previous-line release workflow is running or waiting for approval. Close its remaining PRs with an EOL explanation, including its generated release PR.
2. Delete the previous line's exact merge-queue ruleset, then create an active exact-branch EOL ruleset with an update rule, no bypass actors, and update_allows_fetch_and_merge: false. Keep the branch, tags, releases, images, and charts for reproducibility.
3. Read everything back. Verify release/A.B rejects all updates and release/X.Y has its queue.
4. Merge the generated release PR through the queue under the stable-cut authorization. Wait for every build and the automatic publication job. Download the exact release-helm-chart and release-image-* artifacts and complete Verify Stable Publication in platform/dev/RELEASE.md. Confirm publication completed: the GitHub release is stable and latest, the chart exists, every image version exists, and the companion and agent latest tags resolve to the saved digests. archestra/platform:latest stays on a newer RC if one is published.
5. Open and queue a PR on release/X.Y that removes only the temporary release-as. Leave always-bump-patch, prerelease: false, and draft: true. Future fixes now produce X.Y.1, X.Y.2, and so on.
6. Report that X.Y is the sole supported stable line.

5. Start The Next Beta Line

The next beta is a separate consequential release. Stop and present a second approval with the intended X.(Y+1).0-beta.1 version, current main SHA, configuration PR, and generated release PR. Do not change main or merge the beta release PR until explicitly authorized.

After authorization:

1. Open a PR to main setting packages.platform to versioning: prerelease, prerelease: true, prerelease-type: beta, temporary release-as: X.(Y+1).0-beta.1, and draft: true.
2. Merge it through the main queue. Wait for and verify the generated X.(Y+1).0-beta.1 release PR, then merge it through the queue.
3. Confirm the beta release and versioned artifacts published, archestra/platform:latest moved to it, and the companion and agent latest tags did not move.
4. Open and queue a cleanup PR on main removing only release-as. Confirm Release Please resumes its rolling beta PR for .2 and later.

The initial migration from stable 1.3.x started 1.4.0-beta.1; do not use that historical exception when deriving later versions.

Safety And Recovery Rules

• Qualification: Finish release qualification before merging the release PR. Preserve required CI, image CVE checks, migration checks, the release freeze, and publication ordering guards. Verify the exact saved build artifacts (release-helm-chart and release-image-*) after automatic publication.
• Workflow owns publication: The GitHub Actions workflow handles container image pushes, chart publication, and git tags. Never push release images, publish Helm charts, or update latest tags manually.
• Failed build: Re-run failed jobs in the same workflow run.
• Failed qualification: Do not merge the release PR. If an unpublished candidate already exists, cancel the run and delete its GitHub draft release only with explicit recovery authorization, but keep its tag. Fix on main, backport to release/X.Y, set temporary release-as to the next patch (for example, X.Y.1 after a rejected X.Y.0), qualify the fix before merging the new release PR, and verify the new artifacts after publication. Never reuse a failed version number.
• Cutover failure before publication: If the old line was locked but the new workflow cannot begin publication, stop. With explicit recovery authorization, cancel the new run, delete its blocking draft but keep its tag, restore the old exact merge queue, and remove its EOL rule before accepting old-line changes. When the cut resumes, fix and backport the cause and use the next patch version; never recreate the tagged candidate.
• Partial publication: Keep the draft release and tag. With explicit retry authorization, re-run failed jobs in the original run using the saved artifacts; the retry can publish automatically. Never rebuild already published versions or move latest backward.
• Older workflow revisions: Existing runs and reruns retain their original environment references. Do not approve pending deployments, change live environment protections, delete environments, or retry publication as part of a workflow-only update. Inspect the affected run and obtain explicit authorization for each consequential action.
• Explicit authorization: Stable and next-beta cut approvals may cover their stated branch pushes, configuration PRs, release PR merges, and repository-setting changes. Approving an older run's deployment, deleting draft releases, and any action outside the approved plan still require explicit authorization.
• No hidden handoffs: Create PRs, queue them, monitor checks, configure rules, and verify releases directly. Ask a human only for the two cut approvals, an older run's deployment approval, or an exceptional recovery decision.