SfSkills Domains Docs GitHub

Home / devops / devops-center-pipeline

devops-center-pipeline

Use when setting up, managing, or troubleshooting a Salesforce DevOps Center pipeline — including pipeline stages, work items, bundles, promotions, conflict resolution, and GitHub connectivity. Trigger keywords: DevOps Center, work item, pipeline stage, promote changes, bundle. NOT for CLI-based deployment or SFDX commands — use devops/salesforce-cli-automation. NOT for change sets — use devops/change-set-deployment. NOT for unlocked packages — use devops/unlocked-package-development.

Open the skill folder on GitHub

DevOps Center Pipeline

This skill activates when a practitioner needs to set up, operate, or troubleshoot a Salesforce DevOps Center pipeline — the point-and-click release management tool built natively in Salesforce. It covers pipeline design, work item lifecycle, bundle promotion, GitHub integration, and conflict resolution. It does NOT cover SFDX CLI deployments, unlocked packages, or change sets.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Work Items

A Work Item is DevOps Center's unit of work — analogous to a user story or task. When a Work Item is started, DevOps Center automatically creates a feature branch in the connected GitHub repository. All metadata changes tracked in that org are associated with the Work Item's branch. Work Items move through pipeline stages one at a time and carry their changes forward. Each Work Item has a status: In Progress, Ready to Promote, Promoted, or Merged.

Key constraints:

Pipeline Stages

A pipeline stage represents one environment in the release path. Each stage is associated with:

The typical stage sequence is: Development → QA → UAT → Staging → Production. Stages are ordered and promotions flow in one direction only — you promote forward, never backward. If a regression is found in UAT, you fix it in a new Work Item starting from Development.

DevOps Center creates and manages these branches automatically. The production stage's branch is typically main. Intermediate stage branches are created and managed by DevOps Center; practitioners should not rename or delete them manually.

Bundles and Promotion

Before changes are promoted from one stage to the next, they must be packaged into a Bundle. A Bundle is a snapshot of one or more Work Items selected for joint promotion. Bundling serves two purposes:

  1. It groups related Work Items that share metadata components, reducing the risk of conflicts between separate feature branches.
  2. It creates an auditable promotion unit — a single deployment from one stage to the next that can be tracked, approved, and rolled back as a group.

Individual vs. bundled promotion: A single Work Item can be promoted individually, or multiple Work Items can be combined into one Bundle before promotion. Combining Work Items merges their feature branches before the promotion, which surfaces and resolves merge conflicts in GitHub before the deployment runs.

Conflict Detection and Resolution

When two Work Items modify the same metadata component in different feature branches, DevOps Center detects the conflict when a promotion or bundle merge is attempted. Conflicts appear in the DevOps Center UI and must be resolved in GitHub — DevOps Center itself does not provide an in-app merge editor.

Resolution path:

  1. DevOps Center flags the conflict during the bundle/promotion step.
  2. The practitioner opens the pull request in GitHub and resolves the conflict there.
  3. Once the PR is merged in GitHub, the promotion can proceed in DevOps Center.

Common Patterns

Mode 1: Simple Linear Pipeline (Admin Team)

When to use: A small admin team with a single Dev sandbox and a production org. Minimal parallel work. Moving from change sets to a source-tracked workflow.

How it works:

  1. Install DevOps Center from AppExchange and assign the DevOps Center Admin permission set to the admin.
  2. Connect to GitHub via the Setup wizard (OAuth). DevOps Center creates a new repository or connects to an existing one.
  3. Create a pipeline with two stages: Development (mapped to the Developer sandbox) and Production (mapped to production).
  4. Create a Work Item for each change. Start the Work Item — DevOps Center creates the feature branch.
  5. Make metadata changes in the Development org. DevOps Center tracks them via source tracking.
  6. Mark the Work Item as Ready to Promote.
  7. Promote the Work Item directly to Production (no bundle needed for single items).
  8. DevOps Center opens a pull request in GitHub, runs the deployment, and merges the PR when successful.

Why not change sets: Change sets have no version history, no rollback capability, and no conflict detection. DevOps Center provides all three while remaining fully point-and-click.

Mode 2: Multi-Stage Pipeline with Bundled Promotions (Mid-Size Team)

When to use: A team running parallel sprints with multiple developers working in separate Work Items that share overlapping metadata components (e.g., shared page layouts, permission sets, or flows).

How it works:

  1. Set up a pipeline with stages: Dev → QA → UAT → Production, each mapped to a different sandbox.
  2. Each developer creates and works on their own Work Items.
  3. At the end of the sprint, a release manager creates a Bundle in the QA stage containing all Work Items ready for QA.
  4. DevOps Center merges all feature branches into the QA stage branch. Any conflicts appear as GitHub pull request conflicts to resolve before the promotion proceeds.
  5. The Bundle is promoted through QA → UAT → Production as a unit.
  6. Each promotion creates a GitHub pull request. DevOps Center merges it and deploys the metadata to the target stage org.

Why bundling matters: Without bundling, two Work Items modifying the same Apex class will conflict when promoted separately. Bundling forces conflict resolution before deployment, not during it.

Mode 3: Combining Work Items to Manage Dependencies

When to use: Two Work Items have metadata dependencies — e.g., a new custom object (Work Item A) and a new flow that references it (Work Item B). Promoting B before A would cause a deployment error.

How it works:

  1. In the DevOps Center pipeline view, select both Work Items.
  2. Use the Combine Work Items action. DevOps Center merges Work Item B's branch into Work Item A's branch.
  3. The combined Work Item now carries both sets of changes and can be promoted as one unit, eliminating the dependency ordering problem.
  4. The original Work Item B is closed; its changes live in the combined item.

Why not promote in order: Manual ordering works once, but as parallel work increases, maintaining promotion order by hand becomes error-prone and blocks unrelated work items that happen to share a component.

Decision Guidance

SituationRecommended ApproachReason
Single developer, two orgs, no parallel workIndividual Work Item promotion, no bundlesBundles add overhead with no benefit when there is no parallelism
Multiple developers, shared metadata componentsBundle all Work Items before QA promotionForces conflict resolution before deployment; audit trail per release
Work Items have a metadata dependencyCombine Work Items before promotingEnsures dependent components travel together; avoids deployment failures
Conflict detected during promotionResolve in GitHub PR, then retry promotionDevOps Center delegates conflict resolution to GitHub; UI flags the state
Scratch orgs needed instead of sandboxesSupported but requires Dev Hub and scratch org definitions; map each stage to a scratch orgScratch orgs are short-lived; ensure the stage org is refreshed before promoting
Team also uses SFDX CLI deployments alongside DevOps CenterSeparate the workflows completely — do not mixCLI deployments to the same org will diverge the DevOps Center source tracking state
Need rollback after a bad production promotionCreate a new Work Item that reverts the change, promote through all stagesDevOps Center has no native rollback button; revert via a new forward promotion

Step-by-step instructions for an AI agent or practitioner activating this skill:

  1. Gather context — confirm the org edition, relevant objects, and current configuration state
  2. Review official sources — check the references in this skill's well-architected.md before making changes
  3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
  4. Validate — run the skill's checker script and verify against the Review Checklist below
  5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Source-tracking drift from out-of-band changes — If a developer makes changes directly in a DevOps Center-managed org using Setup UI actions that DevOps Center is not tracking (e.g., activating a flow, modifying a profile setting), source tracking will capture the change but it may be attributed to the wrong Work Item or become untracked. Always ensure changes are associated with an active Work Item before editing in the org.
  2. Stage branch deletion breaks the pipeline — Pipeline stage branches in GitHub (e.g., stage/qa, stage/uat) are managed by DevOps Center. If a developer deletes or force-pushes to these branches outside DevOps Center, the pipeline enters an inconsistent state that requires manual recovery. Protect these branches in GitHub with branch protection rules.
  3. DevOps Center is NOT the SFDX Metadata API deploy path — Practitioners accustomed to sf project deploy start expect a command-line deploy log. DevOps Center deploys via the Metadata API internally but surfaces only a simplified status in its UI. Detailed deployment errors appear in the Deployment Status page in Salesforce Setup, not in DevOps Center itself — this is a common source of confusion when debugging failed promotions.

Output Artifacts

ArtifactDescription
Pipeline stage designMapping of pipeline stages to orgs, branch names, and promotion sequence
Work Item workflow guideStep-by-step for creating, progressing, and promoting Work Items
Bundle strategyDecision on individual vs. bundled promotion with rationale
Conflict resolution runbookSteps for resolving GitHub PR conflicts flagged by DevOps Center
Pre-production promotion checklistVerification steps before pushing a Bundle to production

Package files