Promotion Branches

Promotion branches (Beta)

A promotion branch carries a chosen subset of the User Stories waiting in a major branch to the next major branch, ahead of the rest of the promotion window. It is a selective merge: instead of merging uat into preprod and shipping everything, you assemble a branch holding only the approved stories.

Feature switch: enablePromotionBranches in config/.sfdx-hardis.yml, default false. Required with it: allowedPromotionSteps, the source and target branches a release manager may assemble a promotion between (- source: uat / target: preprod). promotion:create refuses to run while the list is missing. Everything below is inert while it is off, with one exception noted in Filtering. The feature is in Beta and must be labelled as such in docs and UIs, the way backpromote is.

User documentation: docs/salesforce-devops-promotion-branches.md (https://sfdx-hardis.cloudity.com/salesforce-devops-promotion-branches/). End to end test runbook: the promotion-branches-e2e skill.

Mental model

• Promotion branch = promotion/<source>/<target>/<YYYY-MM-DD>-<HHMM>, for example promotion/uat/preprod/2026-09-06-1430 (UTC minute, -2, -3... only when that name is taken). The shape is fixed, not configurable. Only sf hardis:project:promotion:create builds one, with git cherry-pick -x (-m 1 on merge commits).

• Declaration = the promotion Pull Request lists what it carries in a ```yaml block of its description:

  promotionPullRequests: [482, 487]

  This is the only link back to the stories: a cherry-pick rewrites the commit SHAs, so SHA matching cannot find them. A branch named promotion/... without the block, or a branch with the block but not named promotion/..., is an ordinary branch and gets a warning.

• Carried story = a Pull Request named in that block. sfdx-hardis pulls it into the scope of the job so its deployment actions run, its Apex test classes are selected and its custom behaviors are inherited, exactly as if it had been merged directly.

• Vehicle = a Pull Request that moves other Pull Requests rather than carrying work of its own: a merge between two major branches (always), and a promotion Pull Request (only when the feature is on). Everything else, whatever it is named (feature/, fix/, retrofit/, hotfix/...), carries its own change and is a User Story.

• Single place = a Pull Request number appears in exactly one branch of the DevOps Pipeline, the branch it actually reached. A story a promotion carried away is listed in the target branch, not in the one it was merged into.

• One promotion in flight per step = at most one open promotion Pull Request between two given major branches. promotion:create closes the ones it supersedes (after asking a human, silently in agent mode), and the DevOps Pipeline draws the open one on the arrow between the two branch nodes instead of giving it a branch node of its own.

Invariants

Break one of these and the feature is wrong, whatever the tests say.

1. With enablePromotionBranches: false, deployment behaviour is byte for byte what it was. A promotion/... branch is an ordinary feature branch. The only allowed difference is one informational log line. This is proven by the A/B regression check in the promotion-branches-e2e skill.
2. A promotion never runs actions against the wrong org. A promotion/uat/preprod/... branch whose Pull Request targets main is retargeted by hand: its declaration is ignored (isPromotionPullRequestForItsTarget), scope is the Pull Request alone, with a warning.
3. A Pull Request number appears in a single place in the pipeline diagram: the branch the promotion carried it to (promotedAway hides it from the branch it left).
4. User facing lists show User Stories only. Vehicles are hidden unless the Show merge and promotion Pull Requests toggle is on (diagram and modal), or --include-promotions is passed (release notes).
5. Nothing is silently dropped. A declared Pull Request that cannot be read is reported, not skipped in silence; a promotion whose stories could not be resolved stays in the release notes.
6. Expansion is multi level. A preprod -> main promotion can carry a uat -> preprod promotion, which carries stories. Both levels must resolve.
7. Conflict markers never reach an org, and the reviewer is told why. assertNoPromotionConflictMarkers greps every tracked file, not only the package directories, except the git glob patterns of promotionConflictMarkersIgnoredFiles (files that hold markers on purpose, like the merge conflict lab of the training). It reads the checked out files only, never the history, so a shallow CI clone is enough. It stops the job before anything is deployed, so no other code would ever post a Pull Request comment: it sets deployErrorsMarkdownBody / status: 'invalid' on the Pull Request data and calls GitProvider.managePostPullRequestComment(checkOnly) before throwing. A red job with no comment on the very Pull Request that has to be fixed is not an acceptable outcome.
8. A promotion is never closed before its replacement exists. promotion:create closes the superseded Pull Requests only after the new one has been created, so a failure while cherry-picking cannot leave a pipeline step with no promotion open.
9. Not knowing is not a reason to act. When the git provider cannot list the open Pull Requests, nothing is closed and the command says so.
10. A vehicle is never carried. The candidate list of promotion:create associates a commit with the Pull Requests of the commits it brought in, and a sync merge from a major branch matches that major branch's own Pull Request. dropVehiclePullRequests removes them (and their deployment actions) before anything is offered, declared or cherry-picked.
11. A branch merged twice is listed once. shouldAddVirtualPullRequest refuses the number-less entry when a real Pull Request of the same branch is already in the group.
12. Superseding gives the stories back. A promotion this run is about to close is not evidence that its stories are already promoted (countsAsAlreadyPromoted): otherwise agreeing to supersede it would leave nothing to assemble.
13. A vehicle is expanded before it is dropped. A promotion merged into the source branch arrives in the next branch as one cherry-picked merge commit that names the promotion, not the stories under it: the -x trailers only survive one level. expandPromotionsInGroups replaces it with what its promotionPullRequests block declares, recursively, before invariant 10 removes it. Without that, a candidate two levels down carries no number, cannot be selected, and its stories are stranded one branch short of production.
14. Which commits a merge brought in is a question about the graph, never about the dates. A cherry-picked commit keeps the author date it had on the branch it came from, so it is older than the merge before it. attributeCommitsToFirstParents walks git rev-list --parents, stopping at the other first-parent commits, oldest merge first. Attributing by date puts the stories of a promotion under the wrong merge, and a promotion assembled from that grouping declares stories whose metadata it does not carry.
15. Every yaml block of a description counts, and a list adds up. mergePrDescriptionYamlBlocks concatenates list values across blocks (without duplicates) and keeps the last value for anything else, so appending a block to name one more Apex test class does not drop the ones declared above it.
16. Nobody promotes on a step the project never declared. allowedPromotionSteps is required as soon as enablePromotionBranches is on: promotion:create stops with promotionCreateAllowedStepsRequired while the list is missing, and with promotionCreateAllowedStepsInvalid when it is there but unreadable. Guessing "every major branch to every merge target" would be a decision the command has no business making. The pure helpers still treat an empty list as no restriction, which is what keeps the deployment jobs and the pipeline diagram working on a project that is mid-configuration. The rule gates creation, never deployment: a promotion assembled outside the list is deployed with a warning, since refusing it would block a branch that is already merged.
17. A vehicle is opened up, never offered whole. A first-parent commit of the source branch that only moves other merges (integration -> uat, a promotion merged into its target) is replaced by the first-parent commits it brought in (splitVehicleMerges, called from listMergedPrsWithCommits only when promotion:create / list-candidates asks for it). On a pipeline where stories are merged into integration, every first-parent commit of uat is one of those syncs: without this, the whole promotion window is a single selectable row and carrying one story carries them all. Two guards keep it honest: only a merge with exactly two parents is opened up (an octopus merge would lose every side but the second), and only when everything it brought in is inside the window being listed, which keeps a back-merge from the target branch whole instead of turning it into a page of rows already delivered. The vehicle stays a boundary of attributeCommitsToFirstParents (extraBoundaries) so the merge after it does not swallow it.
18. A configuration file can stop being readable mid-command. promotion:create commits git conflict markers on purpose, and config/.sfdx-hardis.yml is a file like any other: loadFromConfigFile keeps the last configuration it read from each set of files and falls back to it with a warning (configFileUnreadableUsingPrevious, configFileConflictMarkers) rather than crashing halfway, with a branch assembled and no Pull Request. It only falls back to something it actually read: a project whose configuration is broken from the start still stops.
19. A conflict answer can be given once for the whole promotion. The prompt of cherryPickCandidates offers commit-with-markers-all next to the three PromotionConflictChoice values: it commits the markers like commit-with-markers and fills rememberedChoice, so the rest of the window is handled without asking again (promotionCreateConflictRemembered says so in the log). It is a prompt answer, not a flag value: PROMOTION_CONFLICT_CHOICES stays skip / commit-with-markers / abort, because --on-conflict already applies to every conflict. A promotion window usually conflicts on the same files story after story, so answering ten times in a row is answering once.
20. A resolution nobody can read is not a resolution. buildConflictResolutionPrompt asks the coding agent for a commit message whose body carries one line per conflicting file, naming the story, what the target side had, what the story added and what was kept, and forbids "solved conflicts" / "merged both versions". The reviewer of the promotion Pull Request reads the resolutions from git log, without opening the diff.
21. A branch that was just pushed may not be visible to the provider yet. GitProvider.createPullRequest takes { retries, retryDelayMs } and pushAndCreatePromotionPullRequest passes 3 retries: GitLab answers {"source_branch":["does not exist"]} on a ref its API has not indexed, a fraction of a second after the push that created it. Each attempt starts with findOpenPullRequest, so a create that succeeded while reporting an error is picked up instead of being created twice, and GitProvider.lastPullRequestCreationError carries the reason into promotionCreatePullRequestManual: the fallback message names what the provider said instead of guessing at a missing token. When it still fails, GitProvider.getPullRequestCreateUrl hands the user the provider's own "new Pull Request" form with the source branch, the target branch, the title and the description already filled in. Each provider class builds its own URL (GithubProvider.getPullRequestCreateUrl and the three others, static, from the git remote, so a project with no token gets one too); buildPrCreateUrl drops the description and keeps the link when the URL would go past MAX_PR_CREATE_URL_LENGTH, and the caller then says where to paste it from. Retyping a promotion description is not an option: the promotionPullRequests block is what the deployment jobs read.
22. The git remote is the authority on which project the API talks to. Outside a GitLab CI job (!process.env.GITLAB_CI), GitlabProvider.autoDetectSettings checks a CI_PROJECT_ID coming from the environment or a .env file against the project path of remote.origin.url, and replaces it with a warning (gitlabProjectIdMismatch) when they disagree. A leftover CI_PROJECT_ID from another repository makes every call answer about that other project, which looks exactly like a branch that does not exist.
23. A promotion branch is validated, never deployed. It is the source branch of a Pull Request, like a feature branch: the only job it may run is that Pull Request's validation. A deployment job triggered by the push that created it would send the promotion to the target org before anyone reviewed or merged it. assertPromotionBranchIsNotDeployed stops deploy:smart at the top of run() and names the CI setting to fix, because the answer is to fix the trigger, not to let the job continue. Silent when the feature is off, on a validation job, and with SFDX_HARDIS_DEPLOY_BEFORE_MERGE, where a deployment legitimately runs from the source branch. It raises an error and posts no Pull Request comment: the job that trips it is the branch pipeline of the push, not the validation, and failing the Pull Request over it would say the promotion is broken when it is the pipeline configuration that is.
24. A promotion branch always runs two pipelines, and only one of them is its Pull Request's. It is pushed to the server, so it gets a branch pipeline of its own next to the Pull Request validation pipeline, on the same commit. In vscode-sfdx-hardis, GitProviderGitlab.pickMergeRequestPipeline reads the newest merge_request_event pipeline (the newest of all of them when the project runs none), which is how GitLab picks the head_pipeline its own merge request page shows; reporting every pipeline of the commit drew a green merge request red on the DevOps Pipeline diagram. GitLab is the only provider concerned: GitHub already asks for event: "pull_request" runs, Azure DevOps and Bitbucket read builds and statuses attached to the Pull Request. Deployment status is a different question, answered by getJobsForBranchLatestCommit, which leaves the merge request pipelines out. Related project-side trap: an unanchored DEPLOY_BRANCHES regex (/(integration|uat|preprod|main)/ instead of /^(...)$/) matches promotion/integration/uat/..., so every promotion branch push starts the deployment job and fails it. The sfdx-hardis default template is anchored.
25. A User Story is offered once, whatever brought it in. A story a promotion cherry-picked into a branch and an ordinary sync merge delivered again afterwards sits in the window twice, as two commits: dropOfferedTwice keeps the first candidate row, which is the one the command already cherry-picks, so the table a release manager reads never lists the same number twice. Only an exact repeat of the same set of numbers is dropped: a row grouping several Pull Requests (a back-merge, an octopus merge) never hides the finer rows of the stories it holds, and a row with no number is a commit of its own and always stays.
26. Every provider writes its own merge sentence. extractPrNumbersFromMessage and mergedSourceBranches read the Pull Request number and the merged branch out of a merge commit message, and the shapes differ: Merge pull request #N from owner/branch (GitHub), See merge request group/repo!N (GitLab), Merged PR N: (Azure DevOps squash) and Merge pull request N from source into target (Azure DevOps completing without fast-forward, which is what keeps the -x trailers). Miss one and every commit a promotion cherry-picked comes back as a row with no number, so the story it carried can no longer be selected.
27. A description a provider refuses is a promotion nobody can review. Azure DevOps caps a description at 4000 characters and a promotion whose cherry-picks conflicted embeds a coding agent prompt that goes past it: buildPromotionPullRequestBody takes the provider's getMaxPullRequestDescriptionLength() and drops the embedded prompt (saved in hardis-report/ either way) rather than letting the creation fail with the branch already pushed. The yaml declaration, the carried table and the conflicting file list always survive.
28. A promotion branch name is never handed out twice. buildPromotionBranchName stamps the UTC date and minute (<YYYY-MM-DD>-<HHMM>, UTC so two machines in different time zones compute the same name), and computePromotionBranchName adds -2, -3... only when that name is taken, one past the highest counter found, never back into a gap. "Taken" is read from everything that can still carry a name after the branch is gone: listExistingPromotionBranchNames collects local branches, git ls-remote, stale remote-tracking refs, the merge commits of the target branch (extractPromotionBranchNames, the merge sentence of all four providers) and the promotion Pull Requests merged into it in the last two days (rebase, fast-forward and Azure squash merges leave no merge commit naming the branch). createPromotionBranch passes refuseExisting, so a name that still exists stops the command instead of resuming a branch already merged. parsePromotionBranchName (and its mirror in the extension, plus the fallback regex of pipeline.js) still accepts the <YYYY-MM-DD>-<counter> names of the first releases: a promotion assembled before the upgrade can still be open, or waiting in a branch for the next step.
29. A backpromote never touches a promotion branch, and a promotion never sees a backpromote branch. hardis:work:backpromote deploys what was merged in a parent major branch into a developer sandbox from its own technical branch backpromote/<parent branch>/<sandbox name> (a child of the parent branch holding the manual merges only, see the backpromote skill). Whatever branch is checked out when it starts, it commits nothing there: it switches to the backpromote branch. backpromote/* branches join promotion/* and retrofit/* in classifyBackpromoteCurrentBranch and in the extension mirror: the DevOps Pipeline, the release notes and the promotion candidates ignore them, and no CI job runs on them. The backpromote history lives in the "Backpromotes" Pull Request comment, which is not the CI/CD "Deployment Actions" comment: neither side reads the other's.
30. What a story already reached is read from the merged promotions of the step, not from the windows. The window of a branch runs since its last direct merge into the next branch, and a project using promotions may never merge uat into preprod directly again, so a promotion merged into preprod leaves the preprod window at the next go-live while the stories it carried stay in the uat window for months (issue #2260: 292 counted, 129 pending). In the extension, listMergedPromotionsOfSteps (orgConfigUtils.ts) asks the provider (listMergedPullRequestsIntoBranch) for the merged promotions of every branch -> merge target step, bounded by the oldest Pull Request of the source window, and feeds them into the index next to the ones the windows hold; enforceSinglePlacePerPullRequest stays as the fallback for a provider that answers nothing. In the CLI, the branch mode of hardis:doc:release-notes subtracts the same stories (dropAlreadyPromotedPullRequests), while deploy:smart keeps them in scope on purpose (no-op redeploy, actions skipped).