Kit Mapping
The bridge between the strategy layer and the pipeline. Once you have picked a blueprint, this page tells you which parts of the kit to switch on - and what to configure in GitHub around them.
Each blueprint page carries the full, copy-pasteable callers. This page is the overview you compare against.
Reusable workflows per blueprint
| Workflow | B1 | B2 | B3 | B4 | B5 |
|---|---|---|---|---|---|
pr-validation.yml | required | required, on all 4 env branches | required | required, one job per org | required, relaxed threshold |
deployment.yml | on main | per env branch | from main or a release tag | per-org matrix | on uat and main |
scratch-org-ci.yml | optional | optional, on feature/* | gate for modules | core CI | - |
create-scratch-org.yml | optional | optional | recommended | recommended | recommended |
promote.yml | - | story promotion and release bundle | - | B2 chain per org | - |
Key input settings
| Setting | B1 | B2 | B3 | B4 | B5 |
|---|---|---|---|---|---|
delta on validation | true | true | true | true | true |
delta on deployment | false | train false, story and bundle true | true (from the last release) | false | false |
test-level | RunLocalTests | RunLocalTests | RunLocalTests | RunLocalTests | RunLocalTests |
severity-threshold | 3 | 3 | 3 | 3 | 2 |
environment on deployment | production | one per stage | production | one per org | uat, production |
Keep RunLocalTests as the test level for production. RunRelevantTests, introduced as a beta in Spring '26, selects tests from the changed code - but Salesforce itself advises against using it in production pipelines yet. Try it in validation runs first.
Why delta on validation but mostly not on deployment
Validating a pull request only needs to check what the branch changed - that is the fast feedback loop. A promotion between long-lived branches deploys the branch's whole state, because a delta there would silently skip anything an earlier hop missed.
B2's story promotion and release bundle are the exception: environment branches are never merged into each other, so each push carries exactly what one pull request merged - usually one story. Deploy it as a delta with delta-from: ${{ github.event.before }}. Otherwise, delta-from is for the case where you deliberately want to deploy the difference since a release tag.
UI bundles (Multi-Framework)
A Salesforce Multi-Framework project ships React or Angular apps as UIBundle metadata, each an npm project of its own under uiBundles/<name>/. The bundle deploys with its build output - the outputDir of its ui-bundle.json, usually dist/ - which is not committed. Every workflow that deploys therefore takes a build-script: an npm script from your root package.json that the workflow runs right before the deploy, in every blueprint.
{
"scripts": {
"build:ui-bundles": "npm ci --prefix force-app/main/default/uiBundles/myApp && npm run build --prefix force-app/main/default/uiBundles/myApp"
}
}with:
build-script: build:ui-bundles- After the login. The script runs with
SF_TARGET_ORGset to the org being deployed to, because the UI bundle plugins bake that org's API version into the build. Inpr-validation.ymlit also runs after the code review, so the analyzer never scans the installed dependencies and build output. - Keep
node_modules/in your.forceignore. The Salesforce project template already lists it; without it, the installed dependencies would be deployed with the bundle.
Delta skips changes inside a bundle
In delta mode, sfdx-git-delta only picks up a bundle when its <name>.uibundle-meta.xml changes - a change to its sources, e.g. src/app.tsx, is left out of the delta manifest without a warning. Deploy projects with UI bundles with delta: false, and validate pull requests that change a bundle with delta: false as well.
The build runs with an authenticated org
Dependencies and their install scripts run after the login, so they can reach the org the workflow deploys to. Commit the lock file of every bundle, install with npm ci and keep the dependencies up to date.
Building blocks
All blueprints use get-node-version, sfdx-cli-setup and sfdx-login - the reusable workflows call them for you. The blocks below matter when you compose your own pipeline:
| Block | Where it earns its place |
|---|---|
sfdx-deploy | Everywhere. delta + dry-run is the validation gate; delta-from targets a release tag |
sfdx-run-tests | Everywhere. Apex, LWC (Jest), Flow and agent tests with coverage |
sfdx-agent-deploy | Wherever the project holds Agentforce agents, see Agentforce |
sfdx-code-review | Everywhere. Relax severity-threshold in B5, keep it strict in B3/B4 |
sfdx-create-scratch-org / sfdx-delete-scratch-org | B3 and B4, where scratch orgs are the development environment |
sfdx-package-installation | B3 (dependencies) and B4 (distributing the core, pinned per org) |
sfdx-data-import | Wherever a fresh org needs to be usable - strongest with create-scratch-org.yml |
sfdx-assign-permissions | Wherever a fresh org needs to be usable - create-scratch-org.yml grants permission sets before the data import |
sfdx-apex-execute | B2 and B4, where each promotion may need data migrations - apex-file-path on deployment.yml runs them after a real (non-dry-run) deploy |
Not covered yet
Package version creation and promotion (sf package version create / promote) has no building block. B3 and B4 need it, so that step is currently a direct sf CLI call in your own workflow - the CLI is already installed and authenticated by the time your step runs.
Branch protection
Configure these under Settings → Branches for every long-lived branch in your blueprint.
| Rule | B1 | B2 | B3 | B4 | B5 |
|---|---|---|---|---|---|
| Protected branches | main | integration, uat, preprod, main | main | main | uat, main |
| Default branch | main | integration (train), main (story, bundle) | main | main | uat |
| Require a pull request | yes | yes | yes | yes | yes |
| Required approvals | 1 | 1 | 1 (owning team) | 1 (CODEOWNERS) | 1 (pipeline owner) |
| Required status checks | validation | validation | validation + scratch org CI | validation per org | validation |
| Require up-to-date branches | yes | yes | yes | yes | yes |
| Restrict who can merge | - | release manager on uat/preprod/main | - | CODEOWNERS | pipeline owner |
| Block force pushes & deletions | yes | yes | yes | yes | yes |
GitHub Environments
deployment.yml takes an environment input, and that one input carries two things at once: environment-scoped secrets (so each org has its own credentials, and no job ever sees another org's) and protection rules (required reviewers, wait timers, branch restrictions).
This is what lets one reusable workflow serve every stage and every org. Create one environment per target org, store SFDX_CONSUMER_KEY, SFDX_JWT_SECRET_KEY and SFDX_USERNAME in each, and use secrets: inherit in the caller.
pr-validation.yml takes an environment input too, so validation can run against the org behind each target branch. Give it its own environment per org - for example uat-validation - with the same credentials but no required reviewers or branch restrictions, or every pull request waits for an approval. scratch-org-ci.yml reads the repository secrets of your Dev Hub.
| Blueprint | Environments to create |
|---|---|
| B1 | production |
| B2 | integration, uat, preprod, production |
| B3 | staging, production |
| B4 | one per production org, e.g. eu-production, na-production, apac-production |
| B5 | uat, production |
Add required reviewers to every environment that fronts a production org. That approval is your release gate, and in a segregation-of-duties context it is the control an auditor will ask about.
See Authentication for setting up the JWT flow and producing these secrets.
What no blueprint gives you
Two gaps are the same in all five, because the platform does not solve them:
- Backup and recovery. Salesforce has no rollback. Every blueprint needs an explicit backup solution with a stated RPO and RTO. The pipeline is not one.
- Drift detection. Changes made directly in an org are invisible to the pipeline until they cause a deployment failure. A scheduled diff between the org and the branch is the cheap mitigation, and it belongs in every blueprint.
