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)

1. 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`.

1. 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)

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

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

Gotchas

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

Reference File Index