Managing Release Candidates
Once you have release candidates on the Release Candidates page, you can deploy them, test them, or use them as the basis for a hotfix. This page walks through each action.
Release
Use Release when you want to deploy a candidate to an environment — typically staging, UAT, or production.
How it works
- Click Release on the release candidate you want to promote.
- The dialog shows you the release definition (domain and release name) and a list of indicative work items that will be included.
- Work items are color-coded:
- Green — this release will fully deploy the work item
- Orange — only a partial deployment (other domains still need releasing for the work item to be complete)
- Grey — the work item is linked to a release candidate in a different domain
- If the release candidate has linked release candidates in other domains, you can select or deselect them.
- Review Pre/Post Steps shows the manual deployment steps the candidate carries for each target environment, and which are still outstanding there.
- Confirm the target environment and click Request Release.
What happens after you click Request Release
codev kicks off the release workflow:
- A dry run validates the release — confirming which packages will be deployed and checking compatibility with the target environment.
- The request enters an approval gate. Designated approvers on your team receive a notification and can review, approve, or reject from Workflows > Pending Approvals.
- If the environment gates on manual deployment steps, the release then waits until its outstanding pre-deployment steps are completed in that environment. See Gating releases on pre-deployment steps.
- codev then locks the target environment, deploys the packages, and unlocks it.
- The release appears on the Releases page.
Releasing to multiple environments
If your release candidate has multiple target environments, each environment gets its own approval gate and deploys independently. The whole process is tracked in Workflows > Runs.
Independent means exactly that: a failure in one environment does not stop, cancel, or roll back the deployment to another. Each environment runs its own approval, locks its own org, and deploys on its own — a rejected approval for staging has no effect on production, and a deployment error in one sandbox leaves the others untouched.
The overall release request reflects the combined result:
- Every environment deployed — the run shows Completed.
- No environment deployed (all failed, rejected, or expired) — the run shows Failed.
- A mix — the run shows Partial. Open the run's sub-flows to see each environment's own outcome; rejected and expired approvals count as non-successes.
See Run statuses for what each status means.
The approval gate ensures that nobody deploys to production without review. If your team wants to skip approval for certain environments (like a dev sandbox), that can be configured in your workflow settings.
Get on Sandbox
Use Get on Sandbox when you want to test a release candidate before formally releasing it. This deploys directly — no approval gate, no waiting.
How it works
- Click the sandbox deploy action on the release candidate row.
- Choose one or more target sandbox environments.
- Select an environment profile (default: DEV).
- Optionally enable Force Install to reinstall packages even if they are already present in the target org.
- Click Deploy to Sandbox.
The deployment starts immediately and you can track it in Workflows > Runs.
Patch
Use Patch when you need a hotfix. This creates a new branch from the exact state of a release candidate, so you can fix a production issue without picking up all the other changes that have been merged since.
How it works
- Click the patch action on the release candidate row.
- Confirm the source branch (default: main).
- Click Create Patch Branch.
codev creates a new branch in your repository. It appears as a separate tab on the Release Candidates page. Developers push their fix to this branch, and when the fix is merged, codev builds a new release candidate scoped to the patch — which can then be released through the normal flow.
Validating and deploying changes on the patch branch
Patch branches are named release-patch-<domain>-<release>-<suffix>, so a single wildcard pattern such as release-patch-* matches every patch branch. Two optional setups connect a patch branch to environments:
- Validate the pull requests. A pull request opened against the patch branch is validated like any other. Add a review environment assignment rule with a Branch Pattern of
release-patch-*so each PR is allocated a pool environment or a dedicated org for change validation. - Deploy the patch build. When the fix merges, codev builds the new release candidate. Set an environment's Branch field to
release-patch-*to have that build deploy to the environment automatically — see Deploying to environments by branch. Otherwise, release the candidate when you are ready.
Unbundle
Use Unbundle to remove specific commits from a release candidate — codev rebuilds the candidate without them, keeping everything else. Because it replays your other changes and resolves any conflicts automatically, it has important limitations and is best used on a recent candidate.
See the dedicated Unbundle page for how it works, conflict resolution, and when a revert PR is the better choice.
Release candidate lifecycle
Release candidates move through these statuses as your team works with them:
- Active — ready to be released or tested
- Released — deployed to at least one environment
- Superseded — a newer release candidate exists for the same domain (this one is still deployable if needed)
You can still release a superseded RC. The status is informational — it tells you a newer version is available, but it does not block you from deploying an older one if needed.