forcedotcom/sf-skills / plugins/builder/dx-devops/skills/dx-devops-work-item-manage
dx-devops-work-item-manage
VerifiedUse this skill to manage the full lifecycle of DevOps Center work items — list, create, update, commit changes, perform status transitions, and create pull requests. Update fields like subject, description, and status. Commit changes to work item branches, through the DevOps Center commit API or git. Create pull requests for work item branches via DevOps Center API. Invoke when the user wants to track, find, create, or update a work item, commit changes to a work item branch, advance a work item's status through the pipeline, or create a pull request for code review. Consolidates sf devops work-item and review operations. DO NOT TRIGGER for promotion or deployment operations, or conflict detection.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.2 KB |
| examples/common-workflows.md | markdown | 16.6 KB |
| references/cli-commands.md | markdown | 10.5 KB |
| references/commit-api.md | markdown | 6.2 KB |
| references/review-api.md | markdown | 5.0 KB |
references/commit-api.md
View on GitHub# Commit through the DevOps Center API
Request, response and polling were verified live (dev org + Core hub, work item `WI-000001`, status In Progress). Error codes, no-access preflight behaviour and git-path sync behaviour come from source, not live tests. Use this when the user supplies a dev org alias and the changes are already deployed in that org.
## Contents
- Orgs involved
- Preflight
- Request
- Response and errors
- Polling
- Confirming on the hub
- Differences from the git path
- Known limits
## Orgs involved
| Org | Role | Used for |
|-----|------|----------|
| Dev org | Holds the metadata; where DX Inspector runs | `doceConnectionType`, `commitChanges`, `DevopsRequestInfo` polling |
| Hub org | Holds projects, work items, component lists | `sf devops work-item list`, status checks, confirming the commit |
The dev org reaches the hub server-side through the `ALMDevOpsCenterHub` named credential. The CLI cannot use that credential, so the hub needs its own `sf` login (`--target-org <hub-alias>`).
## Preflight
```bash
sf api request rest "/services/data/v67.0/connect/devops/doceConnectionType" --target-org <dev-org>
```
The commit API is used at `v67.0`; the commands are not tied to the skill's `minApiVersion`. Treat a non-zero exit or an error body as failure for every `sf api request rest` call here (the no-access case was not tested live).
- 2xx with `{"isCore": true, "isManagedPackage": false}` — Core hub; proceed. This call itself goes through the hub named credential, so success is evidence the credential works.
- A failed call (no DX Inspector access, endpoint missing) — fall back to the git path.
- `isCore` not `true`, or `isManagedPackage: true` — this reference covers the Core path only; use the git path.
- Optional: `sf data query --target-org <dev-org> -q "SELECT DeveloperName FROM NamedCredential WHERE DeveloperName = 'ALMDevOpsCenterHub'"`.
## Request
`POST /services/data/v67.0/connect/devops/commitChanges` on the **dev org**. The REST body is the input object itself. Wrapping it in `{"commitChanges": {...}}` fails with `JSON_PARSER_ERROR: Unrecognized field "commitChanges"`.
```json
{
"isCommitCore": "true",
"workItemId": "<hub work item id>",
"projectId": "<hub project id>",
"workItemName": "WI-000001",
"workItemLink": "<url of the work item in the hub>",
"commitMessage": "<message>",
"changes": [
{"fullName": "MyClass", "type": "ApexClass", "operation": "modify"}
]
}
```
- `isCommitCore` is the **string** `"true"`. The Core path needs it together with a non-empty `workItemId`.
- `operation` is `add`, `modify` or `delete`.
- Rebuild the request body for **every** commit. Write it to a temp file (`mktemp`) and delete it afterwards, so a later `git add` cannot pick it up.
- Do not send `dataChanges` or `vcsRepo` (data deployment and the Managed Package path are out of scope).
```bash
BODY=$(mktemp) # write the JSON above to "$BODY"; rm "$BODY" when done
sf api request rest "/services/data/v67.0/connect/devops/commitChanges" \
--method POST --body @"$BODY" --target-org <dev-org>
```
Pass the file with the `@` prefix (`--body @<file>`); without it the CLI treats the path as the literal body.
## Response and errors
Success: `{"reqId": "<uuid>", "status": "SUCCESS"}` — this means the request was accepted, not that the commit finished.
Request-level failures (e.g. `JSON_PARSER_ERROR` from a malformed body) come back as real HTTP errors: surface them and stop. Business failures are returned as HTTP 200 with `status: "ERROR"` and `reqId` holding `CODE:message`. Codes seen in source: `WORKITEM_NEVERED`, `VCS_NOT_AUTHENTICATED`, `COMMIT_API_FAILURE_CORE`, `COMMIT_API_FAILURE_CLIAAS`, `COMMIT_PAYLOAD_ERROR_*`, `COMMIT_DATA_VALIDATION_ERROR`, `COMMIT_FAILED`. Always check `status`, not the exit code alone.
Server-side preconditions: work item not closed (`WORKITEM_NEVERED`); status New, In Progress, In Review or Ready to Promote; the VCS connection is authenticated.
## Polling
There is no status resource. Query the dev org:
```bash
sf data query --target-org <dev-org> --json \
-q "SELECT Status, Message, ErrorDetails, RequestCompletionDate FROM DevopsRequestInfo WHERE RequestToken = '<reqId>'"
```
- Terminal `Status` values: `SUCCESS` (not `COMPLETED`) and `ERROR`. A loop that waits for `COMPLETED` never exits.
- The commit observed took about 10 seconds. Poll every 10 seconds, deadline 12 minutes.
- `IN_PROGRESS` comes first; `RequestToken` equals the POST `reqId`.
- At the deadline the request is stuck (worker timeout is 10 minutes and the status can stay in progress). Report it and do not retry automatically; a retry is a new request that could race the stuck one.
- `Message`/`ErrorDetails` carry the failure text when `Status` is `ERROR`.
## Confirming on the hub
```bash
sf data query --target-org <hub-org> --json \
-q "SELECT Name, CommitReference, CreatedDate FROM WorkItemComponentList WHERE WorkItemId = '<id>' ORDER BY CreatedDate"
```
A new row with a `CommitReference` hash confirms the commit was recorded. A new row with a null `CommitReference` (seen with unchanged components) means the request succeeded but nothing new was committed; report "nothing to commit", not a successful commit. An In Progress work item stays In Progress; a New one is expected to move to In Progress (not tested live).
## Differences from the git path
| | Git path | API path |
|---|---|---|
| Committed content | Files on local disk | Components named in `changes`, retrieved from the dev org |
| Orgs | Hub only | Dev org for the commit, hub for lookup and confirmation |
| Author | The user's git identity | `DevOps Center <noreply@salesforce.com>` |
| Branch | Work item `branch` field | The work item name (`WI-000001`); the live test could not distinguish this from `branch` |
| Hub records | Created when the hub's external-commit sync picks the push up (only for In Progress, In Review, Ready to Promote) | Created immediately |
| Result tracking | git exit codes | `reqId` plus `DevopsRequestInfo` |
## Known limits
- No rebase before push: a concurrent push to the same branch can make the commit fail as non-fast-forward.
- An empty change set can finish `SUCCESS` with nothing committed.
- A failed attempt can leave an orphaned component list on the hub.
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 |