forcedotcom/sf-skills

dx-devops-request-status

Use this skill to poll the status of an asynchronous DevOps Center request — a promotion or deploy operation.

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/forcedotcom/sf-skills --skill dx-devops-request-status

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

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:
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)
  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:
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)

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

  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

ConstraintRationale
Read-only — never mutate pipeline stateThis skill only reports status; promotion/deploy/complete are owned by other skills
A request token is mandatoryStatus cannot be checked without the -i/--request-token from the promote response; never fabricate one
sf devops request status must use --jsonStructured output is required for headless consumption; human-readable output is unreliable to parse
Read .result.status and .result.errorDetails via jq, never by eyeballingDeterministic 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 FAILEDerrorDetails 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 tokenReal 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 secondsDOCe API rate limits; unbounded fast polling risks throttling
Bound every polling loop with a timeoutPrevents infinite waits and turn/timeout exhaustion in CI
Never run sf devops promotion complete from this skillFinalization is the caller's step after this skill confirms success
Pass the token as a CLI flag, never interpolate into shell stringsPrevents prompt/command injection via crafted tokens
Never use interactive promptsSkills run headless; all inputs must be CLI flags

Gotchas

IssueResolution
No request token providedSTOP and ask for it, or obtain it from the prior dx-devops-promote promote response. Never guess
`status: "SUCCESS"` but the deploy actually failedThe 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 objectIt 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 completeTerminal 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 setRun sf org display --json; if it fails, instruct the user to run sf org login web --set-default
Rate-limit / throttle errors while pollingIncrease the interval (back off); never poll below the 5-second floor
Infinite waitAlways pass a timeout to scripts/poll-status.sh; on timeout, report the last status rather than blocking
Confusing request failure with skill failureA 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

WhenAction
A promotion or deploy must be initiated first to get a request tokenDelegate to dx-devops-promote
Outcome is success (finished, errorDetails null) and the promotion still needs finalizingHand back to dx-devops-promote to run sf devops promotion complete
Status reports Failed due to a metadata conflictReport the conflict from errorDetails; hand back to dx-devops-promote to resolve and re-promote

Reference File Index

FileWhen to read
references/cli-commands.mdWhen you need the sf devops request status flags, JSON output schema, status-value vocabulary, or error-handling patterns
examples/polling-workflows.mdWhen the user's request matches a common pattern (one-shot check, poll-until-done after a promote, timeout handling, failure reporting)
scripts/poll-status.shPhase 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

Relacionados por tarefa

do mesmo repositório

Mais Skills

Todos os Skills
forcedotcom
Comunidade

design-systems-slds-apply

Apply SLDS-compliant UI using the correct blueprints, styling hooks, utility classes, and icons. Use when building any UI that needs SLDS, choosing between Lightning Base Components and SLDS Blueprints, applying styling hooks for theming, using utility classes for layout and spacing, or selecting icons. Triggers include \"build a modal\", \"create a form\", \"data table\", \"SLDS styling\", \"style with hooks\", \"add an icon\".

Instalações / 1h
1
GitHub Stars
1,2 mil
Atualizado
13 de nov.
forcedotcom
Comunidade

dx-code-analyzer-run

Run Salesforce Code Analyzer to scan code for security, performance, best practice, and code style violations. Supports all engines (PMD, ESLint, CPD, RetireJS, Flow, SFGE, ApexGuru), targets (files, folders, git diff), categories, and severities. Also handles post-scan exploration: filtering results by engine/severity/category/file, and explaining what rules mean. TRIGGER when: user says 'scan my code', 'check security issues', 'run PMD/ESLint', 'find duplicates', 'analyze Flows', 'check vulner

Instalações / 1h
1
GitHub Stars
1,2 mil
Atualizado
13 de nov.
forcedotcom
Comunidade

experience-lwc-accessibility-jest-run

Use ALWAYS when running Sa11y accessibility Jest tests for an LWC — locally before pushing, producing the command(s), running one file vs a suite, selecting tests by naming convention, saving Sa11y-rendered HTML, or reproducing a Sa11y/A11yBug failure. Covers core (Bazel; bazel test // : ) and standalone npx jest (.accessibility.test.js, @sa11y/jest). REQUIRED for a run-plan.md, a failing a11y test's exit code, or SA11Y/A11yBug/core-Bazel test paths. DO NOT TRIGGER for functional Jest tests, a11

Instalações / 1h
1
GitHub Stars
1,2 mil
Atualizado
13 de nov.
forcedotcom
Comunidade

experience-lwc-generate

Lightning Web Components with PICKLES methodology and 165-point scoring. Use this skill when the user creates or edits LWC components, builds wire service patterns, or writes Jest tests for LWC. TRIGGER when: user creates/edits LWC components, touches lwc//.js, .html, .css, .js-meta.xml files, or asks about wire service, SLDS, or Jest LWC tests. DO NOT TRIGGER when: Apex classes (use platform-apex-generate), Aura components, or Visualforce.

Instalações / 1h
1
GitHub Stars
1,2 mil
Atualizado
13 de nov.