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

Release dialog
Requesting a release for a selected candidate

Use Release when you want to deploy a candidate to an environment — typically staging, UAT, or production.

How it works

  1. Click Release on the release candidate you want to promote.
  2. The dialog shows you the release definition (domain and release name) and a list of indicative work items that will be included.
  3. 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
  4. If the release candidate has linked release candidates in other domains, you can select or deselect them.
  5. Review Pre/Post Steps shows the manual deployment steps the candidate carries for each target environment, and which are still outstanding there.
  6. Confirm the target environment and click Request Release.

Artifact overrides

Artifact overrides card in the Deployment Options of the Request Release dialog, with one package overridden
An override on one package: it runs two test classes, one added and one removed against the package's own list

An artifact override changes how one package of the candidate deploys for this release only: its test level, the Apex test classes Salesforce runs, and the components left out of the deployment. The artifact and the release candidate are not changed, so later releases deploy the package as it was built. A typical use is a package that queues far more tests than the change needs.

Only users with the Owner role see the Artifact overrides card. It is under Deployment Options in the Request Release dialog.

  1. Under Artifact overrides, choose a package from Add package. The override editor opens.
  2. Set the override, then click Done. The card shows one line per package with its test level, the number of test classes, and the classes added and removed against the package's own list.
  3. Enter a Reason. It is required, and it is shown to the approver and in the run.
  4. Click Request Release. The button stays disabled until the reason is filled in and every list is valid.
Override editor for one package, with its test classes ticked, an Add test classes field and an Ignore components field
The override editor for a package whose own test classes are listed for ticking

In the editor:

  • Test level — Package default, RunSpecifiedTests, RunLocalTests or RunRelevantTests.
  • Test classes — when the package has a list of test classes (bound to it, or the package's own), the list is shown with a tick per class. Untick a class to take it out, paste names into Add test classes to run more, or click Clear all to start from an empty list. A package that has no list, such as a diff package built to run relevant tests, shows a field to paste the classes to run. Names can be separated by commas or new lines. Duplicates and invalid names are flagged, and Runs N test classes shows the final list.
  • Ignore components — Type:FullName entries, one per line, left out of this release's deployment.
  • Reset to the artifact removes the package's override, so it deploys as built.

The work item the request creates has an Artifact overrides section with each package's test level, full class list and ignored components, and the reason, so the approver sees them before approving. A request without overrides shows None there.

Every override is checked against the artifacts and the target org before anything is deployed. A package that is not in the release, a test class that is in neither the package nor the org, or a component that is not in the package fails that environment's dry run, and no approval is requested for it. The run's log lists each override before the package deploys.

An override applies only to a package that deploys. If the package version is already installed in the org, it is skipped and the override has no effect; enable Force Install to deploy it with the override.

Retrying a release with overrides

Artifact overrides card in the Retry dialog of a release job, prefilled with the job's override
The Retry dialog of a release job, prefilled with the override it ran with

A release run that carries overrides shows an Artifact overrides pill on the run and on each environment's release job in Workflows > Runs. Hover over it to see the packages, their overrides and the reason.

Retrying a failed or cancelled release job keeps its overrides. In the Retry dialog, an owner can edit them with the same card and editor; a changed override needs a new reason, and the retried job asks for approval again. Other users see the overrides read-only and can retry the job with them unchanged.

Baseline gaps

A diff package's artifact contains only the changes from its start commit to the commit it was built from. When a target environment's baseline for the package is older than that start commit, the changes in between are not in the artifact, and releasing the candidate does not bring them to that environment. codev checks every diff package of a candidate against the baseline of each active release environment on the candidate's branch, and shows the result on the candidate and in the Request Release dialog. For how baselines work and what happens to a baseline when such an artifact is deployed, see When an artifact starts after an environment's baseline.

On the candidate

Baseline gaps section of a release candidate with a gap on prod and no baseline on uat
The Baseline gaps section: core-crm starts after prod's baseline, and uat has no baseline yet

An environment with a gap is ringed in red in the candidate's deployment stages, and the Overview shows Baseline gap on environment with Open Baseline gaps. The Baseline gaps section lists one card per environment, gaps first. For each diff package it shows:

  • Baseline gap — the environment's baseline and the artifact's start commit, and the files in the package changed by the commits between them. Expand the file count to see the files.
  • Couldn't check — the commits could not be compared, for example because the git provider did not answer. Nothing is blocked.
  • no baseline — the environment has no baseline for the package yet, so there is nothing to compare.

Open environment's baselines opens the environment's baseline page.

Changes section of a release candidate with one commit marked Not in this artifact
The Changes section: one of the two listed commits is not in the artifact

The Changes section lists the commits between the candidate and the previous version. It shows how many of them the candidate's artifacts contain, for example 1 of 2 commits are in the artifacts, and marks the others Not in this artifact. Hover over the badge to see where the package's artifact starts. When the commits of a package's artifact can't be listed in full, its commits are counted as not checked and none of them is marked.

In Request Release

Request Release dialog with a Baseline gap on prod alert, Release anyway ticked and a reason entered
An owner releasing over a gap on prod, with a reason

The dialog shows an alert for each included target environment with a gap, and Request Release stays disabled:

  • Exclude the environment under Target Environments to release to the others.
  • Users with the Owner role can tick Release anyway and enter a Reason. The reason is required. The work item the request creates gets a Baseline gaps acknowledged section with each environment, package and both commits, and the reason.
  • Other users see Exclude environment or ask an owner to release it.

If codev can't check an environment, the dialog shows a note, and the release is not blocked.

What happens after you click Request Release

codev kicks off the release workflow:

  1. A dry run validates the release — confirming which packages will be deployed and checking compatibility with the target environment.
  2. The request enters an approval gate. Designated approvers on your team receive a notification and can review, approve, or reject from Workflows > Pending Approvals.
  3. 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.
  4. codev then locks the target environment, deploys the packages, and unlocks it.
  5. 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

Get on Sandbox dialog
Deploying a release candidate to a sandbox for testing

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

  1. Click the sandbox deploy action on the release candidate row.
  2. Choose one or more target sandbox environments.
  3. Select an environment profile (default: DEV).
  4. Optionally enable Force Install to reinstall packages even if they are already present in the target org.
  5. Click Deploy to Sandbox.

The deployment starts immediately and you can track it in Workflows > Runs.

Patch

Patch dialog with a companion candidate from another domain selected
Creating a patch branch from a release candidate, with a companion candidate from the sales domain

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.

A patch branch can also carry release candidates from other domains. Add a companion candidate when the fix spans more than one domain, or when another domain's packages must match one of its candidates rather than the source branch.

How it works

  1. Click the patch action on the release candidate row. This is the originating candidate; its domain and release name go into the branch name.
  2. Optionally select companion candidates from other domains, one per domain. Available companions lists suggestions; select a row to add it.
  3. To use a candidate that is not suggested, click Add domain, choose the domain, and choose a Release candidate. Load older candidates pages further back through the domain's history, including finalized candidates.
  4. Confirm the source branch (default: main).
  5. Click Create Patch Branch.

codev creates one new branch in your repository from the source branch, with the packages of every selected candidate set to the versions in that candidate. Packages that are not part of a selected candidate keep their state on the source branch. The branch 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 for each domain the change affects — which can then be released through the normal flow.

If any selected candidate's artifacts cannot be fetched, the request fails and no branch is created.

Companion suggestions

Suggestions are listed in this order, and each row states why it was suggested:

ReasonMeaning
Same commitThe candidate was built from the same commit as the originating candidate
Shared work itemsThe candidate shares one or more work items with the originating candidate
Baseline available atThe most recent candidate in that domain on the same branch at the time the originating candidate was created. Shown only for a domain with no other suggestion

Work-item and baseline suggestions consider the five most recent eligible candidates per domain, on the same branch as the originating candidate and created before it. Candidates that were aborted, or that do not record a version for every package, are not offered as suggestions or under Add domain.

A suggestion indicates that two candidates are associated; it does not check that they work together. Validation of the pull requests into the patch branch does that.

Validating and deploying changes on the patch branch

Patch branches are named release-patch-<domain>-<release>-<suffix> after the originating candidate, 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 candidates. 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 candidates 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.

On this page