DevOps Center Request Status

Polls the status of an asynchronous DevOps Center request — a promotion or deploy operation — by its request token via

sf devops request status

. Provides headless,

--json

-driven, read-only status checks for autonomous release workflows in CI. This skill never mutates pipeline state; it only reports the current status of an in-flight or completed request.

Scope

In scope: Check the status of a single async request by its request token; interpret the two-level outcome (request-processing
```
.result.status
```
vs. the
```
.result.errorDetails
```
failure oracle); poll with backoff until a request finishes or a caller-supplied timeout is reached; surface parsed error details on failure
Out of scope: Initiating a promotion or deploy (use
```
dx-devops-promote
```
), work item creation/status updates (use
```
dx-devops-work-item-manage
```
), conflict detection, running
```
sf devops promotion complete
```
(that is the caller's next step after this skill confirms success), pipeline or project setup

Required Inputs

Gather or infer before proceeding:

Request token (required): the request token returned in the
```
dx-devops-promote
```
promote response. Passed via
```
-i/--request-token
```
. Without it, this skill cannot proceed — ask for it or obtain it from the prior promote step's output
Target org:
```
-o/--target-org <alias>
```
(required unless the
```
target-org
```
config variable is set)

Defaults unless specified:

Output format:
```
--json
```
for headless consumption
Polling interval: 10 seconds between checks; cap total wait at a caller-supplied timeout (default 30 minutes). Never poll faster than every 5 seconds — DOCe API rate limits apply

If the user gives a clear request ("check request a0B…", "poll request a0B… until it finishes"), proceed once you have the request token.

Workflow

All operations use

sf devops request status

with

--json

output. This skill is read-only — it issues no mutations. The command's flags and JSON output schema are documented in

references/cli-commands.md

Phase 1 — Authenticate and confirm the request token

Verify org authentication before any operation:
bash
```
sf org display --json
```
- If it fails, instruct the user to run
```
sf org login web --set-default --alias <alias>
```
- Pass
```
-o/--target-org <alias>
```
  on every subsequent command (required unless the
```
target-org
```
  config variable is set)
Confirm you have a request token. If the user initiated a promotion in the same session, reuse the request token captured from the
```
dx-devops-promote
```
promote response. If no token is available, STOP and ask for it — do NOT guess or fabricate a token.

Phase 2 — Single status check (two-level semantics)

CRITICAL:
.result.status
(uppercase, e.g.
SUCCESS
) reports whether the async request finished processing — NOT whether the underlying deploy succeeded. A request can show
status: "SUCCESS"
while the deployment itself failed. The real outcome oracle is
.result.errorDetails
: non-null
errorDetails
means the operation failed, even when
status == SUCCESS
.

Run a single status check with
```
scripts/poll-status.sh --once
```
, which queries the request once and derives the true outcome deterministically (glob-matches the operation-prefixed
```
.result.status
```
suffix, then applies the
```
.result.errorDetails
```
failure oracle). Do NOT hand-roll the JSON parsing in prose — the script owns the two-level rule so it stays consistent with the polling path:
bash
```
scripts/poll-status.sh --once <request-token> <target-org-alias>
```
Interpret the exit code (the script prints a human-readable line to match):
- ```
0
```
  — request finished and the operation succeeded (
```
errorDetails
```
  null) → hand back to the caller
- ```
2
```
  — request finished but the operation FAILED (status suffix
```
*FAILED*
```
  /
```
*ERROR*
```
  /
```
*CANCELED*
```
  , or a
```
*SUCCESS*
```
  status with non-null
```
errorDetails
```
  ) → the printed line carries the parsed
```
errorType
```
  /
```
errorMessage
```
- ```
4
```
  — request is still processing (non-terminal suffix) → proceed to Phase 3 to poll, or report in-progress for a one-shot check
- ```
1
```
  — query/usage error (bad token, auth, or missing dependency)

Phase 3 — Poll until terminal (only when asked to wait)

Poll with a bounded loop when the user asks to wait for completion. Run
```
scripts/poll-status.sh
```
and report the final status it prints:
bash
```
scripts/poll-status.sh <request-token> <target-org-alias> [interval-seconds] [timeout-seconds]
```
- The script polls every
```
interval-seconds
```
  (default 10), never sleeps past
```
timeout-seconds
```
  , stops on a terminal request state, and applies the same two-level outcome check as
```
--once
```
  . Exit codes:
```
0
```
  = finished + succeeded (
```
errorDetails
```
  null),
```
2
```
  = finished but the operation failed (
```
errorDetails
```
  set, or status suffix
```
*FAILED*
```
  /
```
*ERROR*
```
  /
```
*CANCELED*
```
  ),
```
3
```
  = timeout,
```
1
```
  = query/usage error
- It is a read-only loop — it issues only
```
sf devops request status
```
  queries, never mutations
- Do NOT hand-roll a polling loop in prose; the script enforces the interval floor, exact timeout, terminal-state detection, and the
```
errorDetails
```
  outcome check deterministically

Phase 4 — Report

Report the outcome:
- On success (finished,
```
errorDetails
```
  empty): "Request
```
<token>
```
  completed successfully." — then remind the caller that promotion finalization (
```
sf devops promotion complete
```
  ) is the next step, owned by
```
dx-devops-promote
```
- On failure (finished,
```
errorDetails
```
  set — even if
```
status == SUCCESS
```
  ): "Request
```
<token>
```
  failed." plus the
```
errorType
```
  /
```
errorMessage
```
  parsed from
```
errorDetails
```
  and the
```
message
```
  field — do NOT retry or remediate here; that is the caller's decision
- On timeout (still processing): report the last observed request status and the elapsed wait; suggest polling again later — do NOT report success or failure for a request that has not finished processing

Rules / Constraints

Constraint	Rationale
Read-only — never mutate pipeline state	This skill only reports status; promotion/deploy/complete are owned by other skills
A request token is mandatory	Status cannot be checked without the `-i/--request-token` from the promote response; never fabricate one
`sf devops request status` must use `--json`	Structured output is required for headless consumption; human-readable output is unreliable to parse
Read `.result.status` and `.result.errorDetails` via `jq` , never by eyeballing	Deterministic parsing prevents misreading a still-processing request as done
A `SUCCESS` status is NOT proof of success — check `errorDetails`	`.result.status` reports the async request finished, not that the deploy succeeded; a `PROMOTE_SUCCESS` request can carry a failed deploy in `errorDetails`
Non-null `.result.errorDetails` means the operation FAILED	`errorDetails` is the outcome oracle; it is an escaped JSON string ( `errorType` / `errorMessage` ) that must be parsed with `jq` / `fromjson`
`.result.status` is operation-prefixed — match the suffix, not a bare token	Real values are `PROMOTE_IN_PROGRESS` / `PROMOTE_SUCCESS` / `DEPLOY_FAILED` ; exact-matching bare `IN_PROGRESS` / `SUCCESS` would misclassify (and a poller would hang until timeout)
A request is only "done" at a terminal suffix ( `SUCCESS` / `FAILED` / `ERROR` / `CANCELED` )	Reporting an `_IN_PROGRESS` / `_PENDING` / `*_QUEUED` request as done corrupts the caller's release decision
Never poll faster than every 5 seconds	DOCe API rate limits; unbounded fast polling risks throttling
Bound every polling loop with a timeout	Prevents infinite waits and turn/timeout exhaustion in CI
Never run `sf devops promotion complete` from this skill	Finalization is the caller's step after this skill confirms success
Pass the token as a CLI flag, never interpolate into shell strings	Prevents prompt/command injection via crafted tokens
Never use interactive prompts	Skills run headless; all inputs must be CLI flags

Gotchas

Issue	Resolution
No request token provided	STOP and ask for it, or obtain it from the prior `dx-devops-promote` promote response. Never guess
`status: "SUCCESS"` but the deploy actually failed	The most important trap: a `SUCCESS` status only means the request finished. Check `.result.errorDetails` — if non-null, the operation FAILED. Parse it: `jq -r '.result.errorDetails \| fromjson \| "\(.errorType): \(.errorMessage)"'`
`errorDetails` is a string, not an object	It is escaped JSON (e.g. `"{\"errorType\":\"DEPLOYMENT_FAILURE\",...}"` ); pipe through `fromjson` before reading `.errorType` / `.errorMessage`
Status is operation-prefixed ( `PROMOTE_SUCCESS` , `DEPLOY_FAILED` )	Match on the suffix with globs ( `SUCCESS` , `FAILED` ); exact-matching bare `SUCCESS` / `FAILED` misclassifies a prefixed value — a poller would treat `PROMOTE_IN_PROGRESS` as unknown and hang until timeout
Reporting a still-processing request as complete	Terminal suffixes are `SUCCESS` / `FAILED` / `ERROR` / `CANCELED` ; treat `_IN_PROGRESS` / `_PENDING` / `_QUEUED` / `_NEW` / `*_STARTED` as not done — keep polling or report in-progress
No default org set	Run `sf org display --json` ; if it fails, instruct the user to run `sf org login web --set-default`
Rate-limit / throttle errors while polling	Increase the interval (back off); never poll below the 5-second floor
Infinite wait	Always pass a timeout to `scripts/poll-status.sh` ; on timeout, report the last status rather than blocking
Confusing request failure with skill failure	A `Failed` request status is a valid result — report it clearly; do not treat it as a skill error or retry blindly

Output Expectations

Deliverables vary by mode:

Single check:
```
.result.status
```
(request-processing state) plus the derived outcome — on failure, the
```
errorType
```
/
```
errorMessage
```
parsed from
```
.result.errorDetails
```
and the
```
.result.message
```
field
Poll-to-completion: the derived terminal outcome (succeeded or failed, per the
```
errorDetails
```
check) plus elapsed wait, or the last observed request status if the timeout was reached first

Outputs are derived from

sf devops request status

. This skill produces no artifacts and mutates nothing.

Cross-Skill Integration

When	Action
A promotion or deploy must be initiated first to get a request token	Delegate to `dx-devops-promote`
Outcome is success (finished, `errorDetails` null) and the promotion still needs finalizing	Hand back to `dx-devops-promote` to run `sf devops promotion complete`
Status reports `Failed` due to a metadata conflict	Report the conflict from `errorDetails` ; hand back to `dx-devops-promote` to resolve and re-promote

Reference File Index

File	When to read
`references/cli-commands.md`	When you need the `sf devops request status` flags, JSON output schema, status-value vocabulary, or error-handling patterns
`examples/polling-workflows.md`	When the user's request matches a common pattern (one-shot check, poll-until-done after a promote, timeout handling, failure reporting)
`scripts/poll-status.sh`	Phase 2 — invoke with `--once` for a single deterministic status check; Phase 3 — invoke without `--once` to poll a request token with a bounded interval and exact timeout until it reaches a terminal state

dx-devops-request-status

NPX Install

Tags

SKILL.md Content