dx-devops-request-status
Use this skill to poll the status of an asynchronous DevOps Center request — a promotion or deploy operation. Provide the request token returned by dx-devops-promote (the promote response) to check completion, monitor progress, or verify success or failure via sf devops request status. TRIGGER when the user wants to check whether a promotion or deploy finished, monitor an in-flight async request, poll until a request completes, or confirm a request succeeded before finalizing. DO NOT TRIGGER for initiating a promotion or deploy (use dx-devops-promote), for work item creation or status transitions (use dx-devops-work-item-manage), or for conflict detection. Read-only status check — never mutates pipeline state.
- Installs
- 790
- Last 24h
- +11
- Trending rank
- #8503
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/forcedotcom/sf-skills --skill dx-devops-request-status- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads dx-devops-request-status automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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.statusvs. the.result.errorDetailsfailure 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 (usedx-devops-work-item-manage), conflict detection, runningsf 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-promotepromote 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 thetarget-orgconfig variable is set)
Defaults unless specified:
- Output format:
--jsonfor 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:
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 thetarget-orgconfig variable is set)
- If it fails, instruct the user to run
-
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-promotepromote 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 showstatus: "SUCCESS"while the deployment itself failed. The real outcome oracle is.result.errorDetails: non-nullerrorDetailsmeans the operation failed, even whenstatus == 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.statussuffix, then applies the.result.errorDetailsfailure 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:Interpret the exit code (the script prints a human-readable line to match):scripts/poll-status.sh --once <request-token> <target-org-alias>0— request finished and the operation succeeded (errorDetailsnull) → hand back to the caller2— request finished but the operation FAILED (status suffix*FAILED*/*ERROR*/*CANCELED*, or a*SUCCESS*status with non-nullerrorDetails) → the printed line carries the parsederrorType/errorMessage4— request is still processing (non-terminal suffix) → proceed to Phase 3 to poll, or report in-progress for a one-shot check1— 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.shand 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 pasttimeout-seconds, stops on a terminal request state, and applies the same two-level outcome check as--once. Exit codes:0= finished + succeeded (errorDetailsnull),2= finished but the operation failed (errorDetailsset, or status suffix*FAILED*/*ERROR*/*CANCELED*),3= timeout,1= query/usage error - It is a read-only loop — it issues only
sf devops request statusqueries, never mutations - Do NOT hand-roll a polling loop in prose; the script enforces the interval floor, exact timeout, terminal-state detection, and the
errorDetailsoutcome check deterministically
- The script polls every
Phase 4 — Report
- Report the outcome:
- On success (finished,
errorDetailsempty): "Request<token>completed successfully." — then remind the caller that promotion finalization (sf devops promotion complete) is the next step, owned bydx-devops-promote - On failure (finished,
errorDetailsset — even ifstatus == SUCCESS): "Request<token>failed." plus theerrorType/errorMessageparsed fromerrorDetailsand themessagefield — 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
- On success (finished,
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, theerrorType/errorMessageparsed from.result.errorDetailsand the.result.messagefield - Poll-to-completion: the derived terminal outcome (succeeded or failed, per the
errorDetailscheck) 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 |
FAQ
What does the dx-devops-request-status skill do?
Use this skill to poll the status of an asynchronous DevOps Center request — a promotion or deploy operation. Provide the request token returned by dx-devops-promote (the promote response) to check completion, monitor progress, or verify success or failure via sf devops request status. TRIGGER when the user wants to check whether a promotion or deploy finished, monitor an in-flight async request, poll until a request completes, or confirm a request succeeded before finalizing. DO NOT TRIGGER for initiating a promotion or deploy (use dx-devops-promote), for work item creation or status transitions (use dx-devops-work-item-manage), or for conflict detection. Read-only status check — never mutates pipeline state.
How do I install dx-devops-request-status?
Run npx skills add https://github.com/forcedotcom/sf-skills --skill dx-devops-request-status in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/dx-devops-request-status/ (personal) or .claude/skills/dx-devops-request-status/ (project).
Which AI agents can use dx-devops-request-status?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is dx-devops-request-status safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains dx-devops-request-status?
It is published by forcedotcom in forcedotcom/sf-skills. It has 790 recorded installs.
More from forcedotcom/sf-skills
platform-apex-generate
forcedotcom/sf-skills
Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex.
platform-apex-test-generate
forcedotcom/sf-skills
Use to generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking, assertions, and disciplined test-fix loops. Use when creating Apex test classes (for triggers, services, controllers, batch jobs, queueables, and callouts), improving coverage, debugging or fixing failing Apex tests, or running test/coverage analysis. Triggers on Test.cls files, sf apex run test, coverage reports. Do NOT trigger for production Apex (use platform-apex-generate) or Jest/LWC tests.
platform-apex-test-run
forcedotcom/sf-skills
Apex test execution, coverage analysis, and test-fix loops with 120-point scoring. Use when the user runs Apex tests, checks code coverage, fixes failing tests, or touches Test.cls / Test.cls files. DO NOT TRIGGER when writing Apex production code (use platform-apex-generate), Agentforce agent testing (use agentforce-test), or Jest/LWC tests (use experience-lwc-generate).
platform-apex-logs-debug
forcedotcom/sf-skills
Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe).
platform-soql-query
forcedotcom/sf-skills
Use when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan/selectivity analysis, and performance or safety improvements. TRIGGER when the user writes, optimizes, or debugs SOQL/SOSL, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER for bulk data operations (use platform-data-manage), Apex DML logic (use platform-apex-generate), or report/dashboard queries.
platform-metadata-deploy
forcedotcom/sf-skills
Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, validates a deploy or does a dry-run, deploys to a Production org, quick-deploys a validated job ID, ships/promotes to prod, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code, building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate), deleting metadata from an org (use platform-destructive-deploy), or querying org data (use platform-data-manage).
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.