Validated releases

Validate a release candidate against each environment before approval, then quick deploy exactly what was validated.

Validated releases are available only in certain scenarios. Request Validated Release is off by default and is turned on per project. A release can be validated only when it has exactly one source or diff package, after exclusions and with no linked releases; for any other release the Validate before releasing switch is disabled and says why, and a request for an ineligible domain is rejected.

A validated release checks the release candidate against each target environment before the approval request, and after approval deploys exactly what was checked. It is run by the Request Validated Release workflow, which takes the same release request as Request Release.

For each environment, codev first deploys the candidate in check-only mode: Salesforce compiles the components, runs the Apex tests the release calls for, and commits nothing. The approver sees the result of that validation. After approval, codev quick deploys the validation: Salesforce commits the validated deployment without compiling it again or running the tests again.

Use it for a domain that releases a single source or diff package, to environments where the validation runs Apex tests. For how sfp validates and quick deploys a release, see Check-only release and quick deploy.

Turning it on

Request Validated Release is off by default. Workflows > Configuration lists it in the Release section, marked Off by default. A project owner turns it on there, or in the Workflow Settings dialog on the Releases page. The switch applies to the whole project.

While it is off, a request for it is refused with Flow 'request-validated-release' is disabled for project ….

Sending release requests to it

With Request Validated Release on, you choose per request or for the whole project.

For one request. The Request Release dialog shows a Validate before releasing switch, off by default. With it on, the request runs Request Validated Release. The switch is available when the release has exactly one source or diff package; otherwise it is disabled and says why, for example Needs exactly one source or diff package. This release has 3 packages. Artifact overrides are not offered while the switch is on, because Request Validated Release refuses them.

For every request in the project. In the Workflow Settings dialog on the Releases page, a project owner turns on Send release requests here under Request Validated Release. The switch is available only while Request Validated Release is on. It sets a flow override that routes Request Release to Request Validated Release, and removing it deletes the override. While it is on, the Validate before releasing switch in the Request Release dialog shows on and cannot be changed.

You can also set the override with the CLI:

sfp flows set-override --flow-type request-a-release-to-release-envs \
  --override-flow-type request-validated-release --repository your-org/your-repo

The override applies only while Request Validated Release is on; while it is off, release requests run Request Release as usual. In Workflows > Configuration, Request Release shows Routed to Request Validated Release while the override applies, and Override inactive while it does not. sfp flows remove-override --flow-type request-a-release-to-release-envs removes it. See sfp flows set-override.

The project-wide setting routes every release request of the project, including those for domains that are not eligible, which are rejected (see Requirements). A single request can also be sent directly with sfp flows run, with request-validated-release as the payload's id.

Artifact overrides are not supported. A request that carries them is refused with artifactOverrides is not supported by request-validated-release: a check-only validation and its quick deploy run the artifacts as published. Leave Artifact overrides empty when the request goes to Request Validated Release.

What happens in each environment

Each target environment runs on its own, and the request shows Completed, Partial or Failed as described in Releasing to multiple environments.

  1. Validate. codev locks the environment, runs a check-only release of the candidate, and unlocks the environment. Nothing is committed to the org. The run's log shows the validation's deployment id.
  2. Approve. The approval request is sent, with the same gates as Request Release: approvers, manual deployment steps and expiry. It states what approval will start: a quick deploy of the validation, or a full release and the reason. The environment is not locked while the request waits. Salesforce keeps a validation for 10 days, so when approval will start a quick deploy, the request expires at least two hours before the validation does, or earlier if the project's approval expiry is shorter.
  3. Deploy. On approval, codev locks the environment and quick deploys the validated deployment. The post-deployment steps and the release record follow as for any release, and the environment is unlocked. The environment's outcome is quick-deployed.

Rejecting the approval, or letting it expire, cancels that environment, and nothing is deployed to it.

The run's summary names each environment's outcome, for example staging: success (quick-deployed) or staging: error (quick-deploy-rejected) — <reason>.

Seeing a validation and its outcome

The release candidate's Overview has a Validated deployments card with a row for each environment, from its latest validated release. The row shows the state, when the validation ran, its test level, the tests that passed and failed, code coverage, whether it qualifies for a quick deploy (and why not when it does not), and a link to the run. Hovering the state explains it.

Validated deployments card on a release candidate's Overview, with a staging row marked Quick deployed and its validation details
A release candidate's validation on staging, quick deployed after approval

The same state shows on the environment's Releases list and in its release sheet, on the environment's row in the run, and in the approval dialog next to Approve. While a validation waits for approval, its row in the run reads Validated · waiting for approval to quick deploy, or to deploy in full when it cannot be quick deployed.

A validation that passed shows Validated until it is deployed. While it waits for approval, it can also show:

  • Stale: a later deployment to the same org discarded it. The explanation names that deployment and when it ran.
  • Expired: it is more than 10 days old.

Salesforce refuses to quick deploy a stale or expired validation, so codev warns Approving will not quick deploy: Salesforce will refuse this validation. Request the release again to validate it afresh. Stale counts only the deployments made by sfp; a deployment made outside it, for example from Setup, is not shown, and Salesforce still refuses the quick deploy.

After approval, the state is the outcome: Quick deployed, Full deployment with its reason, Quick deploy rejected, Deployment failed or Cancelled. A validation that did not pass shows Validation failed with the failed tests or error, and a release that cannot be validated shows Cannot be validated with the reason. An environment with no validated release shows nothing extra.

Requirements

RequirementIf it is not met
The release deploys exactly one package, of type source or diff, from one release definitionThe environment is rejected with the reason, for example A check-only release validates a domain that deploys exactly one package; … deploys 2 (…). Nothing is deployed and no approval is requested.
The target is a registered codev environmentThe environment fails; a validated release needs the environment's lock.
The validation runs Apex testsAfter approval, the environment gets a full release instead of a quick deploy.
Nothing else deploys to the org between the validation and the approvalSalesforce refuses the quick deploy and nothing is deployed.

The package count is taken after packages skipped for the environment are left out. For the full rule, see Eligibility.

Salesforce quick deploys only a validation that ran Apex tests. A production environment always runs them. A sandbox runs them only when the environment's Test on Install setting is on. When the validation ran no tests, the log shows Running a full release: the validation ran no Apex tests, so Salesforce cannot quick deploy it, and the environment is released in full after approval.

Outcomes and troubleshooting

OutcomeWhat happenedWhat to do
quick-deployedSalesforce committed the validated deployment.Nothing.
full-deploymentThe validation ran no Apex tests, so the environment was released in full after approval.To quick deploy to a sandbox, turn on its Test on Install setting.
rejectedThe release is not eligible. Nothing was deployed and no approval was requested.Release the candidate with Request Release: remove the override, or turn Request Validated Release off, and request it again.
validation-failedThe check-only release failed, for example on a test or coverage failure. Nothing was deployed and no approval was requested.Fix the cause and request the release again.
quick-deploy-rejectedSalesforce refused the validation, with its reason, for example There have been deploys in the org since the source validate happened. Nothing was deployed.Re-run the request.

A validation stays usable only until the next deployment to the org. Any deployment that reaches the org after it, including another validated release that was approved first, makes Salesforce refuse it. There is no automatic fallback to a full release. When several validated releases to one environment wait for approval, the first one approved quick deploys and each later one is refused. Each later one shows Stale from that deployment on (see Seeing a validation and its outcome).

Re-running the request validates the candidate again from the start, against the environment as it is then, and asks for approval again. It never reuses the earlier validation.

Turning it off

Turn Request Validated Release off in Workflows > Configuration or in the Workflow Settings dialog on the Releases page. Later release requests, including re-runs of requests that were routed to it, run Request Release. Runs already in progress finish as they started. An override left in place shows Override inactive.

On this page