Skip to content

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 ​

WorkflowB1B2B3B4B5
pr-validation.ymlrequiredrequired, on all 4 env branchesrequiredrequired, one job per orgrequired, relaxed threshold
deployment.ymlon mainper env branchfrom main or a release tagper-org matrixon uat and main
scratch-org-ci.ymloptionaloptional, on feature/*gate for modulescore CI-
create-scratch-org.ymloptionaloptionalrecommendedrecommendedrecommended
promote.yml-story promotion and release bundle-B2 chain per org-

Key input settings ​

SettingB1B2B3B4B5
delta on validationtruetruetruetruetrue
delta on deploymentfalsetrain false, story and bundle truetrue (from the last release)falsefalse
test-levelRunLocalTestsRunLocalTestsRunLocalTestsRunLocalTestsRunLocalTests
severity-threshold33332
environment on deploymentproductionone per stageproductionone per orguat, 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.

json
{
  "scripts": {
    "build:ui-bundles": "npm ci --prefix force-app/main/default/uiBundles/myApp && npm run build --prefix force-app/main/default/uiBundles/myApp"
  }
}
yaml
with:
  build-script: build:ui-bundles
  • After the login. The script runs with SF_TARGET_ORG set to the org being deployed to, because the UI bundle plugins bake that org's API version into the build. In pr-validation.yml it 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:

BlockWhere it earns its place
sfdx-deployEverywhere. delta + dry-run is the validation gate; delta-from targets a release tag
sfdx-run-testsEverywhere. Apex, LWC (Jest), Flow and agent tests with coverage
sfdx-agent-deployWherever the project holds Agentforce agents, see Agentforce
sfdx-code-reviewEverywhere. Relax severity-threshold in B5, keep it strict in B3/B4
sfdx-create-scratch-org / sfdx-delete-scratch-orgB3 and B4, where scratch orgs are the development environment
sfdx-package-installationB3 (dependencies) and B4 (distributing the core, pinned per org)
sfdx-data-importWherever a fresh org needs to be usable - strongest with create-scratch-org.yml
sfdx-assign-permissionsWherever a fresh org needs to be usable - create-scratch-org.yml grants permission sets before the data import
sfdx-apex-executeB2 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.

RuleB1B2B3B4B5
Protected branchesmainintegration, uat, preprod, mainmainmainuat, main
Default branchmainintegration (train), main (story, bundle)mainmainuat
Require a pull requestyesyesyesyesyes
Required approvals111 (owning team)1 (CODEOWNERS)1 (pipeline owner)
Required status checksvalidationvalidationvalidation + scratch org CIvalidation per orgvalidation
Require up-to-date branchesyesyesyesyesyes
Restrict who can merge-release manager on uat/preprod/main-CODEOWNERSpipeline owner
Block force pushes & deletionsyesyesyesyesyes

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.

BlueprintEnvironments to create
B1production
B2integration, uat, preprod, production
B3staging, production
B4one per production org, e.g. eu-production, na-production, apac-production
B5uat, 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.

Released under the MIT License. · llms.txt for AI agents