forcedotcom/sf-skills / skills/dx-devops-promote
dx-devops-promote
VerifiedUse this skill to drive the full DevOps Center promotion workflow for work items and pipeline stages — validate preconditions, prepare work items, optionally combine work items that share metadata, promote one or more work items or an entire stage to a target pipeline stage, and complete the promotion to finalize the deployment. TRIGGER when the user wants to promote a work item, advance changes to the next environment or stage, combine work items for a single promotion, or move metadata through the release pipeline. The mandatory validate step runs automatically at the start. DO NOT TRIGGER for work item creation or status updates (use dx-devops-work-item-manage), for conflict detection, or for polling an existing promotion's status.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.9 KB |
| examples/promotion-workflows.md | markdown | 8.6 KB |
| references/cli-commands.md | markdown | 10.7 KB |
references/cli-commands.md
View on GitHub# DevOps Center Promotion CLI Commands Reference
Complete reference for the `sf devops` promotion commands with JSON output schemas and error handling. All commands support `--json` and `--target-org <alias>`. Every command is keyed on **record IDs**, not work item names.
## Command Summary
| Command | Purpose | Required Flags | Async? |
|---------|---------|---------------|--------|
| `sf devops promotion validate` | Validate work item promotion to a target stage | `--work-item-id`, `--target-stage-id` | No |
| `sf devops work-item prepare` | Prepare one work item for promotion | `--work-item-id`, `--target-stage-id` | No |
| `sf devops work-item combine` | Combine child work items into a parent | `--parent-work-item-id`, `--child-work-item-id`, `--target-stage-id` | No |
| `sf devops promote` | Promote work item(s) or a stage to a target stage | (`--work-item-id` XOR `--stage-id`), `--target-stage-id`; add `--skip-validation` only if Phase 1 validate passed this session | Yes |
| `sf devops promotion complete` | Finalize the promotion in the target stage | `--target-stage-id` | No |
**Org authentication** — verify before any command:
```bash
sf org display --json
```
---
## Validate (Mandatory First Step)
Validates whether the specified work item(s) can be promoted to the target stage — checks for VCS and object-permission errors before a promotion is attempted. Requires `--target-stage-id`; repeat `--work-item-id` to validate multiple work items in one call.
```bash
sf devops promotion validate \
--work-item-id 1fkxx0000000001AAA \
--target-stage-id 1QVxx0000000001AAA \
--target-org myorg \
--json
```
### Key Flags
| Flag | Description |
|------|-------------|
| `-i, --work-item-id` | Work item to validate for promotion (required, repeatable) |
| `-t, --target-stage-id` | Target pipeline stage to validate promotion to (required) |
| `-o, --target-org` | Target org alias |
### JSON Output Schema (success)
```json
{
"status": 0,
"result": {
"success": true,
"errorType": null,
"errorDetails": null,
"combineDetails": null,
"suggestions": []
},
"warnings": []
}
```
### JSON Output Schema (success, work items share components)
When multiple work items share metadata, validation still succeeds (`success: true`) but returns `combineDetails` and `suggestions` describing whether to combine before promoting:
```json
{
"status": 0,
"result": {
"success": true,
"errorType": null,
"errorDetails": null,
"combineDetails": {
"parentWorkitemId": "1fk000000000001",
"childWorkitemsId": ["1fk000000000002"],
"sharedComponentsList": {
"1fk000000000001": ["MyApexClass", "MyTrigger"],
"1fk000000000002": ["MyApexClass"]
}
},
"suggestions": [
"The selected work items share one or more components. Choose one of these approaches:",
"Option 1 - Combine the work items and promote them as a single unit: ...",
"Option 2 - Promote the work items as they are, without combining: ..."
]
},
"warnings": []
}
```
### Interpreting the result
- **Success:** `status == 0` and `.result.success == true`. Proceed.
- **Shared components:** if `.result.combineDetails` is non-null, the work items share metadata. Use `.result.combineDetails.parentWorkitemId` / `.childWorkitemsId` to drive the combine decision in Phase 2 (see Combine), then promote the parent. This is the authoritative signal for whether to combine — don't guess.
- **Failure:** a non-zero exit code. The command surfaces an error such as `Validation failed (VCS_ERROR): No pull request exists for the work item on the source branch.`, with `.result.errorType` / `.result.errorDetails` populated in `--json`. STOP — do not prepare/combine/promote. The `VCS_ERROR` case confirms the associated-PR requirement is enforced here.
---
## Prepare
`--target-stage-id` is required (the pipeline stage the work item is being prepared to promote to).
```bash
sf devops work-item prepare --work-item-id 1fkxx0000000001AAA --target-stage-id 1QVxx0000000001AAA --target-org myorg --json
```
### JSON Output Schema
```json
{
"status": 0,
"result": {
"workItemId": "1fkxx0000000001AAA",
"prepared": true
}
}
```
Idempotent — re-running a prepared work item is a safe no-op.
---
## Combine
Combine one or more child work items into a parent work item so they promote as a single unit. Repeat `--child-work-item-id` once per child.
```bash
sf devops work-item combine \
--parent-work-item-id 1fkxx0000000001AAA \
--child-work-item-id 1fkxx0000000002AAA \
--child-work-item-id 1fkxx0000000003AAA \
--target-stage-id 1QVxx0000000001AAA \
--target-org myorg \
--json
```
### Key Flags
| Flag | Description |
|------|-------------|
| `--parent-work-item-id` | The primary work item that continues through the pipeline |
| `--child-work-item-id` | A work item to merge into the parent (repeatable) |
| `--target-stage-id` | The pipeline stage to promote the combined unit to (required) |
| `-o, --target-org` | Target org alias |
After combining, promote the **parent** work item ID via `sf devops promote`.
---
## Promote (Async)
Exactly one of `--work-item-id` or `--stage-id` must be provided; they are mutually exclusive. `--target-stage-id` is always required. **Pass `--skip-validation` ONLY when the Phase 1 validate step completed successfully this session for every work item being promoted** — `promote`'s built-in pre-promote validation runs the *same* checks (including the associated-PR requirement) as `sf devops promotion validate`. When that validation already ran this session, skipping avoids a redundant re-run; but if the agent resumed mid-workflow or promotion was invoked without a preceding validate, OMIT the flag so the CLI validates.
### Promote one or more work items
```bash
sf devops promote \
--work-item-id 1fkxx0000000001AAA \
--target-stage-id 1QVxx0000000001AAA \
--skip-validation \
--target-org myorg \
--json
```
Repeat `--work-item-id` per item. For a combined promotion, pass the **parent** work item ID.
### Promote an entire source stage
```bash
sf devops promote \
--stage-id 1QVxx0000000000AAA \
--target-stage-id 1QVxx0000000001AAA \
--skip-validation \
--target-org myorg \
--json
```
### Key Flags
| Flag | Description |
|------|-------------|
| `-i, --work-item-id` | Work item to promote (repeatable, mutually exclusive with `--stage-id`) |
| `-s, --stage-id` | Source stage whose approved work items are promoted (mutually exclusive with `--work-item-id`) |
| `-t, --target-stage-id` | Destination pipeline stage (required) |
| `-a, --deploy-all` | Deploy all metadata in the branch, not just changes not yet in the target stage |
| `-l, --test-level` | Apex test level: `NoTestRun`, `RunSpecifiedTests`, `RunLocalTests`, `RunAllTestsInOrg` |
| `--tests` | Specific tests to run when `--test-level RunSpecifiedTests` |
| `--skip-validation` | Skip `promote`'s built-in pre-promote validation. It runs the same checks (including the associated-PR requirement) as `promotion validate`. Pass this ONLY when Phase 1 validate already ran successfully this session; omit it if promotion was invoked without a preceding validate (e.g. mid-workflow resume) so the CLI validates |
| `-o, --target-org` | Target org alias |
### JSON Output Schema
```json
{
"status": 0,
"result": {
"promotionId": "0Af000000000001AAA",
"sourceStageId": "1QVxx0000000000AAA",
"targetStageId": "1QVxx0000000001AAA",
"status": "InProgress"
}
}
```
- Async operation. Capture `.result.promotionId` (some CLI versions use `.result.asyncOperationId`).
- Poll the returned identifier separately to confirm completion — do NOT busy-wait here.
- After the deploy completes, run `sf devops promotion complete` to finalize.
---
## Promotion Complete
Finalize the promotion — advances the promoted work items in the target stage. Run after the promote deploy succeeds. `--target-stage-id` is required (the same target stage the work items were promoted to).
```bash
sf devops promotion complete --target-stage-id 1QVxx0000000001AAA --target-org myorg --json
```
### JSON Output Schema
```json
{
"status": 0,
"result": {
"completed": true,
"targetStageId": "1QVxx0000000001AAA"
}
}
```
---
## Error Handling
**Work item not found:**
```json
{ "status": 1, "name": "NOT_FOUND", "message": "Work item does not exist or is not accessible", "exitCode": 1 }
```
**Not prepared before promote:**
```json
{ "status": 1, "name": "NOT_PREPARED", "message": "Work item has not been prepared for promotion", "exitCode": 1 }
```
**Missing target stage:**
```json
{ "status": 1, "name": "MissingRequiredFlag", "message": "Missing required flag --target-stage-id", "exitCode": 1 }
```
**Conflict on deploy:**
```json
{ "status": 1, "name": "DEPLOY_CONFLICT", "message": "Metadata conflict detected during deployment", "exitCode": 1 }
```
**Authentication failure:**
```json
{ "status": 1, "name": "NoOrgFound", "message": "No org configuration found for target-org. Run 'sf org login web' to authenticate.", "exitCode": 1 }
```
---
## Parsing Async Promotion IDs
```bash
# Promote and capture the promotion ID for status polling.
# --skip-validation is shown here because this snippet assumes Phase 1 validate
# already passed this session; OMIT it if promotion is invoked without a
# preceding validate (e.g. a mid-workflow resume).
PROMOTION_ID=$(sf devops promote \
--work-item-id 1fkxx0000000001AAA \
--target-stage-id 1QVxx0000000001AAA \
--skip-validation \
--target-org myorg \
--json | jq -r '.result.promotionId // .result.asyncOperationId')
echo "Promotion initiated. Promotion ID: $PROMOTION_ID"
# Poll this ID separately, then run: sf devops promotion complete --target-stage-id 1QVxx0000000001AAA --target-org myorg --json
```
---
## Resolving Names to IDs
Promotion commands need record IDs. Resolve a project name and work item subject/name to IDs first:
```bash
# List projects to resolve a project name to an ID
# (project list returns .result.projects[] with capitalized .Id / .Name)
sf devops project list --json | jq -r '.result.projects[] | "\(.Id): \(.Name)"'
# Resolve a work item subject to its ID
# (work-item list returns .result.workItems[] with .id / .subject)
sf devops work-item list --project-id <project-id> --json | \
jq -r '.result.workItems[] | select(.subject == "<subject>") | .id'
```
---
## Authentication Requirements
All promotion commands require:
1. **Authenticated org**: `sf org login web` or JWT auth (for CI)
2. **DevOps Center enabled**: org must have DOCe provisioned
3. **Promotion permissions**: user/service account must be able to promote in the target pipeline
Auth is the caller's responsibility — these skills contain no auth logic. In CI, use a JWT-authenticated service-account alias with least-privilege scopes.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |