Dx Devops Request Status

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

1. Verify org authentication before any operation:

   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)

2. 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.

3. 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:

   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)

4. 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:

   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

5. 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

---