Promotion branches (Experimental)

Promotion branches (experimental)

Experimental feature. Promotion branches are new in sfdx-hardis. They are switched off by default, nothing changes for a project that does not enable them, and their behavior may still change from feedback. Please report anything unexpected in sfdx-hardis issues.

• When to use them
• How it works
• Configuration
• Assemble a promotion branch
• What sfdx-hardis does with it
• After the promotion
• Limits

When to use them

With sfdx-hardis, you promote branches, not features: everything merged into uat goes to preprod, then to production, as one version. This is the recommended way, because the stories of a version were tested together.

Some organizations cannot always follow it. Business sign-off happens per User Story, a stakeholder is on leave, a story comes back from a demo with rework, and a release date is fixed. At that moment uat holds a mix of approved and unapproved stories, and one unapproved story would block every other one.

A promotion branch is the exception path for that situation: a branch cut from the target major branch (usually preprod), on which the release manager cherry-picks the approved stories only, and which is merged through an ordinary Pull Request. It is not a replacement for the normal promotion of uat: use it when you have to, and promote uat as usual as soon as you can.

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#eaf5fe", "primaryTextColor": "#032d60", "primaryBorderColor": "#0176d3", "lineColor": "#0176d3", "secondaryColor": "#f3f3f3", "tertiaryColor": "#ffffff", "fontFamily": "Salesforce Sans, Arial, sans-serif"}}}%%
flowchart TB
    subgraph WINDOW["What is waiting in uat"]
        direction LR
        %% Invisible links keep the four stories on one row, in order: without an
        %% edge between them they would all sit in the first rank and stack up
        OK1["PR 113<br/>Renewal reminders<br/>approved"] ~~~ KO1["PR 114<br/>Contract pricing<br/>waiting for sign-off"] ~~~ OK2["PR 115<br/>Appointment scheduler<br/>approved"] ~~~ KO2["PR 116<br/>Territory rules<br/>waiting for sign-off"]
    end
    WINDOW --> CHOICE{"Is the whole<br/>window approved?"}
    CHOICE -->|Yes| NORMAL["Merge uat into preprod:<br/>the recommended way,<br/>the stories were tested together"]
    CHOICE -->|"No, and the release<br/>date does not move"| PROMO["Assemble a promotion branch<br/>carrying PR 113 and PR 115 only"]
    NORMAL --> PREPROD[["preprod"]]
    PROMO --> PREPROD
    style OK1 fill:#e3f7e8,stroke:#2e844a
    style OK2 fill:#e3f7e8,stroke:#2e844a
    style KO1 fill:#fef1ee,stroke:#ea001e
    style KO2 fill:#fef1ee,stroke:#ea001e

For urgent fixes that were never in uat, use hotfixes instead.

How it works

A promotion branch is an ordinary minor branch for the deployment itself: its Pull Request to preprod gets a delta validation, a Quick Deploy after the merge, the overwrite management, exactly like a hotfix branch.

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#eaf5fe", "primaryTextColor": "#032d60", "primaryBorderColor": "#0176d3", "lineColor": "#0176d3", "secondaryColor": "#f3f3f3", "tertiaryColor": "#ffffff", "fontFamily": "Salesforce Sans, Arial, sans-serif"}}}%%
flowchart LR
    %% Lanes are stacked in reverse declaration order, so preprod is declared
    %% first to draw uat on top, the promotion under it and preprod at the bottom
    subgraph PREPROD_BRANCH["preprod"]
        direction LR
        P0["release 2026-07"] --> PROMOTION_MERGE["merge of the promotion"]
    end
    subgraph PROMOTION_BRANCH["promotion/uat/preprod/2026-08-20-0930"]
        direction LR
        C113["cherry-pick<br/>of PR 113"] --> C115["cherry-pick<br/>of PR 115"]
    end
    subgraph UAT_BRANCH["uat"]
        direction LR
        M113["merge of PR 113"] --> M114["merge of PR 114"] --> M115["merge of PR 115"] --> M116["merge of PR 116"]
    end
    P0 -->|"branch from origin/preprod"| C113
    M113 -.->|"git cherry-pick -x"| C113
    M115 -.->|"git cherry-pick -x"| C115
    C115 -->|"Pull Request declaring<br/>promotionPullRequests: [113, 115]"| PROMOTION_MERGE
    style C113 fill:#e3f7e8,stroke:#2e844a
    style C115 fill:#e3f7e8,stroke:#2e844a

The promotion Pull Request says which stories it carries, so the deployment jobs give them everything they would have had in a normal promotion: their deployment actions run, their Apex test classes are collected, their tickets are updated and the release notes mention them.

The DevOps Pipeline of the VS Code extension draws the promotion in flight on the arrow between the two branches it goes from and to, next to the counter of the User Stories still waiting in uat:

promotionPullRequests: [482, 487, 491]

Configuration

Two settings switch the feature on, both in the Danger Zone of the Pipeline Settings panel of the VS Code extension:

• Enable promotion branches (enablePromotionBranches), off by default;
• Allowed promotion steps (allowedPromotionSteps), the source and target branches your release managers may assemble a promotion between. This list is required: sfdx-hardis refuses to assemble a promotion while it is missing, rather than assume that every major branch can be promoted to every merge target.

With uat -> preprod as the only allowed step, as above:

• the Create promotion button and the checkboxes that tick the stories to carry show up in the uat window only. The other branches show their Pull Requests read-only;
• the target is settled, so nothing is asked: a promotion from uat can only go to preprod;
• a promotion branch assembled outside the list all the same (by hand, or before the list was written) still deploys, and the job logs a warning naming the step and the allowed ones.

enablePromotionBranches: true
allowedPromotionSteps:
  - source: uat
    target: preprod

allowedPromotionSteps:
  - source: uat            # uat to any of its merge targets
  - source: preprod
    target: main

Naming

A promotion branch is named after the step it serves and the minute it was assembled, so the name alone says where the stories come from and where they go:

promotion/uat/preprod/2026-09-06-1430

The convention is not configurable, and the command is what applies it.

promotion/<source branch>/<target branch>/<YYYY-MM-DD>-<HHMM>

Assemble a promotion branch

Everything below is done from the DevOps Pipeline of the VS Code SFDX Hardis extension: you tick, you click, and when a conflict shows up you copy a prompt into your coding agent. Nothing has to be typed in a terminal.

Never assemble a promotion branch by hand: sfdx-hardis is what guarantees the naming, the cherry-pick options and the Pull Request declaration the deployment jobs rely on.

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#eaf5fe", "primaryTextColor": "#032d60", "primaryBorderColor": "#0176d3", "lineColor": "#0176d3", "secondaryColor": "#f3f3f3", "tertiaryColor": "#ffffff", "fontFamily": "Salesforce Sans, Arial, sans-serif"}}}%%
sequenceDiagram
    autonumber
    actor RM as Release manager
    participant CLI as SFDX Hardis
    participant Git as Git repository
    participant CI as CI/CD jobs
    RM->>CLI: Tick the stories, click Create promotion
    CLI->>Git: Read the stories merged in uat and not promoted yet
    CLI-->>RM: Which ones does this promotion carry?
    RM-->>CLI: PR 113 and PR 115
    CLI->>Git: Branch from preprod, cherry-pick each selected merge
    CLI->>Git: Push and open the Pull Request, declaring what it carries
    CI->>CI: Validation: delta check, actions and test classes of PR 113 and PR 115
    RM->>Git: Review, then merge without squashing
    CI->>CI: Deployment to preprod with the same scope

1. Tick the stories to carry

Make sure they are merged into uat and validated there. In the DevOps Pipeline, open the window of the source branch, tick the User Stories to carry, then use Create promotion: it opens with them preselected, and you confirm the selection.

Only the stories waiting in that branch are offered: the target is its merge target (preprod for uat), and a story an earlier promotion already carried there is left out, so the same work is never shipped twice. A story brought into the branch by an earlier promotion is promoted through that promotion and cannot be ticked.

2. Let sfdx-hardis assemble the branch

It creates the branch from the target, cherry-picks the selected stories oldest first, pushes, and opens the Pull Request with a description that declares what it carries and lists the titles, authors, source branches and tickets.

3. Answer the conflicts, if any

If a cherry-pick conflicts, the story depends on another one that is not part of the promotion. You are asked what to do.

💡 Recommended: pick "commit this User Story and every following conflict with their conflict markers, without asking again", then hand the conflicts to a coding agent. A promotion window conflicts on the same files story after story, so answering once beats answering ten times. The promotion is assembled in one go, and the conflicts are all solved afterwards, on the branch, in a single pass.

Once the Pull Request is open, copy the prompt it carries and paste it into your coding agent (Claude Code, Codex, Copilot...). It knows which files to fix and what the resolution has to look like, and it commits the result. The same prompt is saved as a markdown file under hardis-report/, in case the description is not the handiest place to copy from.

The validation job fails while a conflict marker is still in the sources, so a promotion cannot reach the org half-solved.

The four answers in full:

• commit the story and every following conflict with their conflict markers, without asking again (recommended): the promotion is assembled whole, conflicts and all, for the coding agent to solve;
• commit-with-markers: the same for this story only, so you are asked again on the next conflict;
• skip: leave that story out, it is listed as such in the Pull Request description;
• abort: stop, the branch is deleted and nothing is pushed.

The sf-git-merge-driver plugin solves many XML conflicts by itself, so install it and you will see far fewer of them.

A story whose change is already in the target branch (brought by a hotfix, a retrofit or an earlier promotion) has nothing to cherry-pick: it is left out and listed apart in the Pull Request description, without asking anything.

4. Review and merge

Review the Pull Request like any other, and do not squash it when merging: the -x trailers of the cherry-picks must survive in preprod.

The branch itself can be deleted right after the merge, by hand or by a repository that deletes the head branch of every merged Pull Request: a later promotion never takes its name back, because the name of a deleted branch is still read from the merged Pull Requests of the target branch and from its history.

⚠️ A promotion branch must only be validated, never deployed. A promotion branch is the source branch of a Pull Request, like a feature branch. Your CI must run its validation job, never a deployment job: deploying from the promotion branch would send the promotion to the target org before it is reviewed and merged. The deployment job stops with an error when it happens, naming the setting to fix. The usual cause is a deployment trigger that matches more than your major branches.

# promotion/integration/uat/2026-09-08-1430 matches this one
DEPLOY_BRANCHES: /(integration|uat|preprod|main)/
# it does not match this one
DEPLOY_BRANCHES: /^(integration|uat|preprod|main)$/

One promotion at a time between two branches

A pipeline step holds a single promotion in flight, so the DevOps Pipeline can draw it on the arrow between the two branch nodes and there is one answer to "what is being promoted to preprod right now".

When a promotion from uat to preprod is already open and you assemble a new one, the open one is listed and you are asked to confirm before it is superseded. The stories it carried come straight back to the list you tick from.

If your working copy is not clean

Assembling a promotion switches branches and cherry-picks commits, so it needs a clean working copy. When you have local changes, they are not simply refused: they are listed, and you choose to stash them (to restore later) or to commit them on the branch you are on, with the message of your choice. Only the files you changed are touched: the reports sfdx-hardis writes under hardis-report/ are left alone, so getting your work back does not fight with them.

For agents and automation

Agents and automation call the same command without prompts, and can ask what could be promoted without creating anything.

sf hardis:project:promotion:create --agent --source-branch uat --pull-requests 482,487,491

sf hardis:project:promotion:list-candidates --source-branch uat --json

What sfdx-hardis does with it

The promotion Pull Request carries no work of its own: its deployment actions, its Apex test classes and its tickets are those of the stories it declares. The extension shows them read-only, with the list of the Pull Requests they come from:

Custom behaviors are inherited too. If a carried story asked for a specific deployment behavior in its description, the promotion Pull Request inherits it, and the validation comment says which story it came from. What a story declared, it needs in every org it reaches.

After the promotion

Two things to do, both borrowed from the hotfix process:

• Retrofit right away. Once preprod (or production) contains the promotion branch, retrofit it into integration with a retrofit/ branch, exactly as after a hotfix. The cherry-picked commits then meet their originals at the next integration -> uat promotion instead of at the next go-live.
• Freeze uat -> preprod while a promotion branch sits in preprod and has not reached production yet, otherwise unapproved stories ride along. This is the RUN/BUILD rule of the hotfix process.

In the DevOps Pipeline, a promoted story leaves the window of the branch it came from and is listed in the branch it reached, so a Pull Request number appears in a single place in the diagram, both in the counter on the node and in the list opened by clicking it.

A uat window that stays full of already-shipped stories is the sign that uat is used as the approval gate preprod was designed to be. Consider adding an intermediate major branch rather than assembling every version by hand.

Release notes

The release notes list the User Stories a promotion Pull Request carries, not the promotion Pull Request itself: the tickets, the metadata changes, the deployment actions and the contributor counts are those of the stories. A promotion whose declared Pull Requests could not be resolved is kept in the notes, so a change never disappears from them. The same rule applies to the merges between two major branches, which are left out whether or not the project uses promotion branches.

Limits

• A promotion is always assembled from a major branch, never from another promotion branch. A promotion carrying another promotion is fine, and the deployment jobs follow the declarations down as many levels as there are.
• Custom behaviors are inherited on the promotion Pull Request only. On the next preprod -> main promotion, keywords are read from that Pull Request's description, like for any promotion.
• Save / Publish User Story warns when run on a promotion branch: its cleaning and manifest updates are meant for User Story branches.

Pull Request description cache

On Azure DevOps, sfdx-hardis and the VS Code extension have to re-read the description of every promotion Pull Request through a second API call, which dominates the run on a repository with a long history. Descriptions that can no longer change are cached locally to avoid it, and nothing has to be configured.

Comments