Production release
On this page
| Key | Shape | Default | Purpose |
|---|---|---|---|
release.productionBranch |
string | "master" |
Production pull-request base. |
release.releaseSource |
string | "develop" |
Branch promoted to production. |
release.autoDeployOnMerge |
string | none; setup asks | Plain-English description quoted at the owner merge gate. |
release.releaseBranchPattern |
pattern, e.g. "release/<YY-MM-DD>[-n]" |
absent: the release pull request's head is release.releaseSource |
From 3.8.0: cut each production release as its own protected branch from the release source (-2, -3 … on a re-cut) and open the release pull request from it, so the source keeps receiving merges while the release is reviewed; those ship in the next release. Fixes are new commits — never a rebase, amend or force-push — and a hotfix that reaches production meanwhile is merged in and re-reviewed. After the release, release syncs the production branch back into the source by pull request and deletes the release branch once both contain it. Add a matching protectedBranches entry; doctor warns when none matches. |
release.releaseBranchFixExclusions |
array of path patterns, e.g. ["infra/**", "db/migrations/**"] |
absent: nothing is refused | Paths a fix commit on a release branch may not touch — deploy configuration and migrations. Such a fix is refused: merge it to the source by a normal pull request, abandon the release branch and re-cut. The same list keeps one-offs that touch those paths off the release train. |
release.mergeTrainBeforeCut |
boolean | false: nothing is merged into the source before the cut |
With releaseTrain.branch set, every release first merges a snapshot of the train into the source through its own fully reviewed pull request. See Release train. |
release.migrationRenumber |
{ "sqlGlobs": [...], "metaGlobs": [...] } |
absent: a renumber is refused like any other migration change | From 3.22.0: merging the source into the train snapshot can force a reviewed migration to take a new number. With this key set, a commit whose only excluded-path changes are that migration file deleted and re-added under a new name with byte-identical content (sqlGlobs), plus migration metadata files (metaGlobs), is allowed, and the release pull request reports it. |
release.holdTimeZone |
IANA time-zone name, e.g. "America/Chicago" |
"UTC" |
From 3.36.0: the zone a Release hold: not before <date> line is read in, so every machine lifts a hold at the same moment. See Release holds. |
release.productionReview |
{ "reviewIdenticalTree": false, "highRiskPaths": [...], "highRiskEngine": "codex" } |
absent: every engine reviews the production pull request | From 3.13.0, review once. A release whose tree equals the one fully reviewed on its way into the release source gets no second review. The exception is one pass of highRiskEngine over the files it changes under highRiskPaths. A tree changed by a fix or a hotfix merge gets a follow-up review of that difference. With the release train as epicIntegrationBranches.releaseTarget, the train's pull request then reviews only the one-offs no pull request reviewed. |
release.syncWorkflow |
a workflow file, e.g. "sync-master-into-develop.yaml" |
absent: the close-out opens its own sync pull request | From 3.13.0: a workflow that merges the production branch back into the source after every push to production. The close-out waits for it instead of opening a second one, and stops with its link if it is left open. |
release.deployApproval |
string or null |
null |
Optional command for a production deploy that waits for an approval (a protected environment or a manual gate). Your yes to the release is also the approval of its deploy, so the release skill runs it right after the merge, with the merge commit in RELEASE_COMMIT: exit 0 means approved and read back, 2 means the deploy is not waiting yet (it tries again, a bounded number of times), anything else stops the release. You are never sent to the provider's page to approve. When null, the deploy runs on its own. Set it by hand; setup does not ask for it. Since 3.15.0. |
release.deployVerification |
string or null |
null |
Optional command that exits 0 only when production serves the merge commit in RELEASE_COMMIT. The release skill runs it before writing a release note; when null, it asks the owner to confirm the deploy. |
release.devDeployVerification |
string or null |
null: the release does not wait for a development deploy |
From 3.22.0: an optional command shaped like deployVerification, run with RELEASE_COMMIT set to the head the release merges from the release source. Exit 0 means that commit is deployed to your development environment, 2 not deployed yet, 1 the development deploy failed. When the release touches a release.releaseBranchFixExclusions path, the release runs it after your yes and before the production merge, polling every 60 seconds for up to 45 minutes on exit 2; exit 1 or the time limit stops the release, so production is never merged over a failed development deploy. With a standing yes configured, the wait runs before the standing-yes check whatever the release touches. |
release.postDeployCheckSkill |
string or null |
null |
From 3.3.0: the name of a local skill (.claude/skills/<name>/) that checks production health once the deploy is confirmed. null means no check is registered and the close-out reports post-deploy health: not configured. Setup does not write it. Re-run it alone with /devstride:post-deploy. |
release.classifySkill |
string or null |
null: every release is FULL |
From 3.20.0: a local skill that says whether a release is light or full. Called with classify and { "productionBranch", "releaseSource", "head" } at the start of the release and again right before its pre-ship checks, at the head they test. Its first line must be exactly RELEASE CLASS: LIGHT or RELEASE CLASS: FULL, then a reason; anything else, a failing run or a missing skill is FULL. The class prints in the release summary and reaches every pre-ship command as RELEASE_CLASS=light|full. What a light release may skip is your repository's own rule. Step: /devstride:classify-release. |
release.preMergeSkill |
string or null |
null: the summary says pre-merge production check: not configured |
From 3.20.0: a local, read-only skill that says whether production needs anything before the release merges — a migration checkpoint, a backfill, a setting. Called with check and { "productionBranch", "releaseSource", "head", "pullRequest": { "number", "url" } } once the release pull request is green and before you are asked for the go-ahead. First line PRE-MERGE: CLEAR, PRE-MERGE: HOLD (the release stops and names the action) or PRE-MERGE: NOT RUN (reported, and you are asked whether to proceed; never a pass). Step: /devstride:pre-merge-check. |
release.clearance |
null, { "provider": "github" } (optional ref, staleMinutes, waitMinutes, and from 3.16.0 phaseBudgetMinutes), from 3.21.0 { "provider": "devstride" } (optional credentialsFile, staleMinutes, waitMinutes, phaseBudgetMinutes), or { "commands": { … } } (optional phaseBudgetMinutes from 3.27.0); every form takes an optional scope from 3.27.0 |
absent: nothing is claimed | From 3.11.0: one production release at a time, for every machine and account that releases the repository. scope is "release" (the default), "cut-to-deploy" or, from 3.61.0, "merge-and-deploy", which needs release.releaseBranchPattern. See Release clearance. Setup does not write it. |
release.autoStart.enabled |
boolean | false: a release starts only when someone runs /devstride:release |
From 3.29.0: releases start themselves. A one-off landing on the release train, a release unit's release merging onto it, a release finishing its close-out and, from 3.61.0, every story boundary in build-item and a release levelling the train after its deploy each check whether the train holds work the release source does not, and if so claim the one-winner release-train claim and run release in that session. A session that loses the claim carries on with its own work. There is never a second release in flight and no batching timer. Needs a claims block; without one /devstride:doctor reports an error and nothing starts. See Releases that start themselves. |
release.backstop |
{ "mode", "maxWaitMinutes" } |
absent, or mode "off": no backstop check runs |
From 3.45.0: a check run on a schedule (/devstride:release backstop) starts a release when work has waited on the release train too long and nothing is releasing it. mode is "off" (the default), "shadow" (records in the claims store what it would have started and changes nothing) or "live" (starts the release). maxWaitMinutes is a whole number of minutes from 15 to 1440, default 120: how long the oldest landing on the train may wait, counted from when it was merged onto the train. No other keys apart from _ notes. Needs a claims block, and with a claims block of your own commands, claims.commands.get; /devstride:doctor reports either gap as an error, and warns when there is no release train. See Release backstop. |
release.lightRelease.standingYes |
boolean | false: every release waits for the owner's go-ahead |
From 3.29.0: the owner's standing yes for light releases; needs release.classifySkill. A release the classify skill calls light, whose tree is identical to the reviewed train, merges and has its deploy approved without an in-the-moment yes when every condition holds (below). A full release, a changed tree or any failed condition waits for the owner as before, unless release.fullRelease (from 3.37.0) covers it. |
release.fullRelease |
{ "standingYes", "ownerDecision", "migrationGlobs", "approvedMigrations" } |
absent: a release that is not light waits for the owner's go-ahead | From 3.37.0: the owner's written standing yes for releases of any class; needs release.clearance, since without it no release is ever on final and the route always asks. standingYes turns it on (default false); ownerDecision is the date the owner wrote it (YYYY-MM-DD), quoted on every merge it makes; migrationGlobs lists the paths that count as migrations (patterns as in branch matching: * within one path segment, ** across segments); approvedMigrations lists the migration contents the owner approved, each { "blob", "path", "item", "approved" }, where blob is the file's git blob id. An absent or invalid ownerDecision, or an absent or empty migrationGlobs, makes the route ask. /devstride:doctor warns when the yes cannot take effect and refuses a malformed approval. See Releases that start themselves. |
releaseTower |
{ "overrideLabel": "release-tower-override", "hotfixPattern": "*/hotfix/**" } |
those two defaults | From 3.11.0: read by the release-tower GitHub check and by the clearance status. overrideLabel passes a pull request into the production branch that an owner approved by hand; hotfixPattern names the heads that are never held. |
Post-deploy health check#
The plugin does not know what "healthy" means for your production system — alarms, dead-letter queues, error rates, a synthetic transaction — so, exactly as with the documentation hooks below, it holds one fact: the name of a local skill that does. The release skill invokes that skill once, after the production deploy is confirmed and before documentation, release notes, and the close-out (with release.clearance.scope "cut-to-deploy" or "merge-and-deploy", after the clearance is handed back, as the first owed item, posting its verdict as the release/post-deploy commit status), as check followed by a fenced JSON payload of productionBranch, mergeCommit, and deployConfirmedAt.
The skill's first line must be exactly POST-DEPLOY HEALTH: PASS, POST-DEPLOY HEALTH: FAIL, or POST-DEPLOY HEALTH: NOT RUN, followed by evidence lines that each name the command that produced them. PASS continues and carries the evidence into the close-out. FAIL stops the release and asks the owner for a rollback decision — it never continues to documentation or notes on its own. NOT RUN (missing credentials, an unreachable endpoint) is reported as this-run degradation and the owner is asked whether to proceed; it is never a substitute for FAIL. /devstride:doctor checks that a configured name resolves to an existing skill. The full contract is skills/release/references/post-deploy-check.md in the plugin repository.
Release clearance#
When more than one machine, person or agent releases the same repository, set release.clearance so only one release is in flight at a time. /devstride:release then claims clearance before it touches the release train or cuts anything (with scope: "cut-to-deploy", just before it cuts; see below). A second release that asks is told who holds it, on which machine and in which phase, and waits; because a release ships everything on the release source at the cut, the next one carries its work. The holder records each phase as it goes. From 3.16.0 it hands clearance back as soon as the next release could safely start: once the post-deploy check has passed, the production branch is synced back into the release source, the release branch is deleted and the release train is level. Documentation, owed customer replies, local teardown and any release note then run in the same session after the hand-back, and status lists them as Close-out owed on that machine until each is done; before 3.16.0 the hand-back was the last act of the close-out. A failed check keeps the clearance. Nothing ever holds up a hotfix.
Holding it only from the cut to the deploy (scope: "cut-to-deploy", from 3.27.0). The release merges the release train into the source — its review and its one CI run — without clearance, claims clearance just before it cuts the release branch, and hands it back as soon as the deploy is confirmed, the production branch is synced back, the release branch is deleted and the train is level. The post-deploy check then runs after the hand-back, as the first owed item, and posts its result as the release/post-deploy commit status on the production merge commit, which every machine can read. The next release may cut, review and test meanwhile, but it does not merge into the production branch until that status is success, unless the owner overrides it in words recorded on the pull request. A session that stopped after the hand-back leaves the status pending; any session finishes it with /devstride:release post-deploy only. Hotfixes are never held by it. The default, "release", keeps the older order: claim before the train, hand back after the post-deploy check, and no status is posted.
Holding it only for the merge and the deploy (scope: "merge-and-deploy", from 3.61.0). Everything cut-to-deploy does still holds, but clearance is claimed only for the merge into production and the deploy, and releases line up first cut, first merged:
- The queue. No release is cut while another release pull request is open into production; the release waits, checking every minute. So the next release is cut the moment the one ahead merges, and releases merge in the order they were cut. If it has waited behind the same pull request past
staleMinutes, it tells you once which pull request it is waiting behind, in case that release's session has stopped, and keeps waiting; it never adopts it on its own. - Built on top of what is ahead. Right after the cut, when the release source does not yet hold production's latest merge, production is merged into the new release branch before its pull request opens, so the review sees the combined change. The
release-trainclaim is handed on once that pull request is open. - Checked outside clearance. The class, the pre-ship checks, the development deploy wait and the pre-merge check run while the release ahead deploys, and record a check stamp: the tree they tested, production's tip and when they ran. Review and CI follow as usual.
- Claimed on the go-ahead. The release waits, holding nothing, until the previous release's
release/post-deploystatus is success (up to 45 minutes while it is pending). On your yes or the standing yes it claims clearance, reads that status once more, verifies the stamp, re-runs the pre-merge check and anyrerunAtMergepre-ship check, and verifies the stamp again just before the merge. - Rebuilt when production moves. If the release ahead was reverted, a hotfix landed or anything else moved production since the checks, the release steps aside (it gives clearance back and owes nothing), brings production in, has that difference reviewed, and runs its checks and CI again before it may merge; any yes given before is void.
- Handed back at deploy-confirmed. The release marks its merge commit's post-deploy status pending at once, confirms the deploy and hands clearance back. Its post-deploy check runs first, so the release behind merges as soon as this one is healthy; syncing production back into the release source runs after it. A repository with no post-deploy check posts success instead, so it never holds the next release.
This scope needs release.releaseBranchPattern; without one, doctor reports an error and the release stops before it cuts.
- The built-in
githubprovider keeps the clearance on GitHub, in a git reference that is neither a branch nor a tag, so every machine withghsigned in and push access sees the same one. Every change to it is a compare-and-swap, so two machines can never both win it. A claim starts a small background keeper that renews the clearance for as long as the claiming session is running. - The
devstrideprovider (from 3.21.0) keeps the clearance in DevStride instead, as an agent claim of kindrelease-towerkeyed by the repository, which lapses atstaleMinutesif its keeper stops. It behaves exactly likegithub: the same verbs, verdict lines, exit codes andstatus --json, and it still reads pull-request facts throughgh. It signs in with a DevStride API key whose user holds theMANAGE_AGENT_CLAIMSpermission (API Keys group of its role), taken fromDEVSTRIDE_API_KEY,DEVSTRIDE_API_SECRET,DEVSTRIDE_ORG_ID(and optionallyDEVSTRIDE_ORG_SLUG,DEVSTRIDE_BASE_URL) in the environment, or from aKEY=VALUEfile named bycredentialsFile. That file must be your own regular file with no group or other access (chmod 600); any other is refused. The key, the secret and the session's identity are never printed. - A stale clearance — no renewal for
staleMinutes, default 20 — is taken over by the next release when its pull request was never opened or was closed unmerged. When its pull request is still open, or merged but never closed out, the release asks you before adopting it and resuming where it stopped; it is never deleted silently. - A stuck clearance (from 3.16.0) is one that is still renewing but has sat in one phase longer than its budget,
phaseBudgetMinutes(defaults:pre-ship120,deploy60,close-out45 minutes;0ornullswitches a phase's alarm off, and a phase not named has none —reviewandtrainwait on people and CI, and from 3.33.0final, the wait for the owner's go-ahead, is recorded as its own phase so it no longer counts againstpre-ship).status, every BUSY line and the status line show it asSTUCK, naming the holder's session and machine. It is an alarm, never a takeover: a stuck clearance is adopted only on the owner's yes and their word that the original session has stopped (adopt --yes --original-stopped). A release waiting withclaim --waitstops once (exit5) when it finds the holder stuck, so it can tell you, and then waits on withclaim --wait --ignore-stuck. - Whose clearance it is. The holder is one identity for every clearance command:
CLEARANCE_HOLDER_TOKENwhen set (from 3.20.0; the olderDEVSTRIDE_LEASE_TOKENis still read when it is unset), else the agent's own session id. A plain terminal with neither gets a one-time token printed to export asCLEARANCE_HOLDER_TOKEN. Theidentitycommand prints this session's holder, so any tooling of your own that asks "does this session hold clearance?" (a merge guard, for example) should use it, or readCLEARANCE_HOLDER_TOKENfirst by the same rule. - Your own provider: instead of
provider, give five shell commands undercommands—claim,status,heartbeat,releaseandadopt— that follow the same contract, and optionally a sixth,owed(from 3.16.0); without it the release names its owed close-out work in its recap instead. A block with bothproviderandcommands, or aproviderother thangithubordevstride, is a config error that/devstride:doctorreports. - The status line shows a
⚑release segment — the release branch, who holds it and its phase, withSTALEpast the stale threshold andSTUCKpast the phase budget — while a clearance is held; with nothing held it showsclose-out owedwhile this machine still owes close-out work, and nothing otherwise. - The GitHub floor: once clearance is set,
/devstride:setup cioffers therelease-towercheck. On every pull request into the production branch it passes a hotfix and the oldest open release pull request, holds a later release with "… is on final; this release waits" until the first merges or closes, and tells any other branch to retarget. It runs from the repository's default branch, so a pull request cannot edit its own gate. Make it a required check on the production branch's ruleset once it has posted green on one real release — then not even an administrator can land a second release beside the first.
The full contract is skills/release/references/clearance.md in the plugin repository.
Releases that start themselves#
From 3.29.0, with a claims block configured, every release — started by hand or not — first claims the release-train claim (kind release-train, keyed by the repository, claims.expiryMinutes["release-train"], default 30 minutes), before it opens or adopts the train's pull request and before it claims clearance, and keeps it alive through every wait. It hands the claim on once the release branch is cut under clearance (under merge-and-deploy, once its release pull request is open), so the next release's train phase can run while this one deploys. From 3.61.0, with release.autoStart.enabled, build-item also checks at every story boundary and when its loop starts, and a release that wins the claim to level the train after its deploy starts the next release itself when work is waiting. A claims outage never lets a release carry on without it: an automatic start does nothing, and a hand-started one stops and names the outage.
release.autoStart.enabledadds the triggers in the table above. A release that started itself and cannot merge on the standing yes stops at the owner's go-ahead, holding clearance, and sends one notification naming the release, why it is waiting and its pull request.release.lightRelease.standingYesmerges a light release without asking only when all of these hold: a classify skill is configured and calls it light; its tree is identical to the latest reviewed train merged into it; every required check is green; no review thread is unresolved; every pre-ship check passed and none was waived; the pre-merge check is clear; the development deploy check, when configured, has passed; the previous release's post-deploy check is green; and the release is on final in the tower. The release then records one comment on its pull request saying it merged on the standing yes.release.fullRelease.standingYes(from 3.37.0) merges a release of any class without asking when the same conditions hold, with one difference and one addition: its head must be exactly the reviewed head (or review's same-tree re-trigger commit) rather than identical to the train, and every file the release adds or changes undermigrationGlobsmust have its exact content listed inapprovedMigrations. Add an approval only on the owner's own words, in a commit of its own; renaming or renumbering a file keeps its approval, any edit to its content needs a new one. A new, edited or deleted migration without an approval, a waived pre-ship check, a pre-merge hold or any other failed condition waits for the owner.
The full contract is skills/release/references/auto-start.md in the plugin repository.
Release backstop#
From 3.45.0, release.backstop makes sure work that landed on the release train never waits indefinitely because no session noticed it. It does not delay, cap or replace the releases above: those still start whenever work is ready. The backstop is a check you run on a schedule, by hand or from a scheduled session (for example /loop 10m /devstride:release backstop); a dispatcher can run skills/release/scripts/backstop.py due directly.
Each check acts (starts a release in live, records one in shadow) only when all of these hold:
modeisshadoworlive, aclaimsblock is configured, and the train holds work the release source does not.- The oldest landing on the train has waited longer than
maxWaitMinutes. The wait is counted from the time git records for that landing's merge, so every machine computes the same wait. - No release is in progress: no open release pull request into the production branch and, when
release.clearanceis set, clearance reads free. If it cannot read the pull request list or the clearance status, it skips. From 3.61.0, underrelease.clearance.scope"cut-to-deploy"or"merge-and-deploy", neither is read: a release there has already left the waiting work behind once it is cut, so only therelease-trainclaim decides. - No release hold applies to the work the release would carry.
Otherwise it does nothing and says why. Machines checking the same waiting work at the same time compete for one claim in the claims store, keyed by the oldest waiting landing, so only one of them acts. That claim is never renewed: it lapses after maxWaitMinutes, so each piece of waiting work gets at most one start per window. If the release it started stops early (a hold, a red check, your no), the backstop tries again at most once per maxWaitMinutes while the work still waits and nothing else is releasing it.
shadowrecords what the check would have started, in the claims store, and changes nothing: no train claim, no clearance, no branch, no pull request. List therelease-trainclaims whose key starts with<owner>/<repo>@to read the records. Nothing is written to your repository.livestarts the release through the same path as an automatic start, so the unattended stop and the standing yes above apply. Switch it on only after you have checked the shadow records over a representative period: one record for each piece of waiting work, at the right wait, and none while a release was in progress.
off, the default, is also the way back. The full contract is skills/release/references/backstop.md in the plugin repository.
Release holds#
From 3.36.0 a hold is data on the item, never a message or someone's memory. One line in an item's DevStride description, usually the epic's, keeps that work off the release path:
Release hold: not before 2026-11-09lifts at midnight that day inrelease.holdTimeZone(UTC when unset).Release hold: not before 2026-11-11T08:00-06:00lifts at that instant.Release hold: after I20101 is livelifts once I20101 is deployed and checked: withrelease.clearance.scope"cut-to-deploy"or"merge-and-deploy", its production merge (or a later one) carries a successfulrelease/post-deploystatus; other scopes count the merge and say so.
A line that does not parse holds, naming the item and the line. Remove the line to lift a hold early; that edit is the owner's record. The loop reads the item and every ancestor. build-item checks before a one-off merges onto the release train or the base branch, and before an epic releases; held work waits on its own branch. release checks every item before the train snapshot and before the cut, and stops naming the held item; taking work back off the train is the owner's call. The contract is skills/build-item/references/release-holds.md in the plugin repository.