Skip to content

forcedotcom/sf-skills / skills/dx-lifecycle-center

dx-lifecycle-center

Verified

Lifecycle Center for DX Inspector and Builder Central. Four jobs: (A) list the orgs connected to DX Inspector; (B) connect a new org (sandbox or scratch, production, OrgFarm) as a deploy target; (C) connect or check the Lifecycle Center org, also written LifecycleCenter, lifecycle-center, ALMDevOpsCenterHub, or Hub org; (D) deploy, validate, or quick-deploy components that already exist in the user's org to a connected org, and poll a simple-deploy requestId. TRIGGER on: show, list, or pick connected orgs or environments; connect, add, log in to, or repair an org; connect the Lifecycle Center org; deploy, validate, push, or publish components (metadata) to another org, URL, org id, alias, or environment name. Short asks like "connect a new org" or "deploy to my sandbox" match. NOT for promoting work items (dx-devops-promote), local source deploys (platform-metadata-deploy), or publishing sites or packages. Deploys move components between orgs, not local files.

FileKindSize
SKILL.mdskill md13.1 KB
examples/workflows.mdmarkdown12.0 KB
references/connect-api.mdmarkdown9.6 KB
references/connect-org.mdmarkdown19.8 KB
references/deploy.mdmarkdown12.1 KB
references/error-handling.mdmarkdown2.7 KB
references/hub-org.mdmarkdown6.5 KB
references/list-orgs.mdmarkdown11.8 KB
references/request-body.mdmarkdown3.7 KB
references/troubleshooting.mdmarkdown8.4 KB
scripts/hub-get.shexecutablescript2.8 KB
scripts/poll-deploy-status.shexecutablescript9.3 KB
scripts/resolve-environment.shexecutablescript16.3 KB

references/connect-org.md

View on GitHub
# Connecting an Org (Named Credential Setup)

Creates and configures the Named Credential (NC) and External Credential (EC) that DX Inspector uses to call another org, through `/connect/devops/setupNamedCredential`. Use it when the user wants to connect an org, or a deploy needs a target that is not connected yet.

The **development org** is the source org, where DX Inspector runs. It holds every credential, so every API call here targets that org (`<dev-org-alias>`). The org being connected to is touched only through the browser login. API shapes and status checks: `connect-api.md`. Failures: `troubleshooting.md`.

## Modes

| Mode | Used by | NC/EC name | Type field |
|---|---|---|---|
| **Deploy target** | Operation B, and Operation D when its target is not connected | Generated by the server: `<EnvName>_<epochMillis>` (letters only in `EnvName`, which must contain at least one letter). Uses the **Environment API**, which also creates the `DevopsEnvironment` row | `orgType` `PRODUCTION`, `SANDBOX`, or `ORGFARM` |
| **Lifecycle Center org** (the hub) | `hub-org.md` | Fixed: `ALMDevOpsCenterHub` (exact casing). Uses `setupNamedCredential`; no `DevopsEnvironment` row is needed | `ORG_TO_ORG` |

**Why two APIs:** `setupNamedCredential` creates only the NC and EC. It never creates a `DevopsEnvironment` row, and deploy needs that row (`targetEnvironmentId`). For a deploy target always use `POST /connect/devops/environment`, which creates the NC, the EC, and the row in one call.

Target org to type (deploy mode sends `orgType`; hub mode sends `namedCredentialType`, normally `ORG_TO_ORG` for the hub org):

| Target org | `orgType` (deploy) | `namedCredentialType` (hub) |
|---|---|---|
| Production or Developer Edition (logs in at login.salesforce.com) | `PRODUCTION` | `ORG_TO_ORG` |
| Sandbox or scratch org (logs in at test.salesforce.com; both are the same type) | `SANDBOX` | `ORG_TO_SANDBOX_ORG` |
| OrgFarm org | `ORGFARM` | `ORG_TO_ORGFARM_ORG` |

The type picks the login page. The API takes no login URL, and the PATCH later discovers the org's real My Domain from the login. If the user gives an org URL instead of a type, map it by host, checking rows top to bottom (first match wins, so an OrgFarm sandbox is a sandbox):

| Host pattern | Type |
|---|---|
| Contains `.sandbox.` (e.g. `*.sandbox.my.salesforce.com`), or `test.salesforce.com`, or contains `.scratch.` | Sandbox (scratch orgs included) |
| Starts with `orgfarm-` | OrgFarm |
| Other `*.my.salesforce.com`, `login.salesforce.com` | Production |

Read the type from any common spelling, ignoring case, spaces, and hyphens: sandbox, sbx, sand box, test org, scratch, scratch org, scratchorg → `SANDBOX`; production, prod, prd, live, developer edition, dev edition → `PRODUCTION`; orgfarm, org farm, org-farm → `ORGFARM`. A word that fits none of these is not a type: ask.

If the type is still ambiguous (for example only an environment name like "MySandbox", or a vague "connect my org"), **ask the user**; never default. Never infer the type from the environment name: a wrong type sends them to the wrong login host.

---

## Step 0 — Resolve inputs and check for an existing credential

1. Resolve `<dev-org-alias>`: the alias the user named, else the default org from `sf org display --json`. Read `result.apiVersion` as `<ver>`; it must be at least `67.0`; the alias registration below needs `68.0`, and on `67.0` the connect works but no alias is registered, so do not add the flag.
2. Determine the mode. Hub mode only when reached from `hub-org.md`; every other connect is deploy mode. In deploy mode also determine the target org type and a short environment name. The name is also the workspace alias. Spaces are allowed (`Dev 12 Org`), but never `default-org`, and never a name an existing alias already uses for another org: check `bash scripts/resolve-environment.sh "<dev-org-alias>"` for `aliasConflict: true` and `sf alias list` for the name. If it is taken, ask for a different one.
3. Check whether a usable credential already exists (`connect-api.md`, *Check credential status*).
   - **Hub mode:** check `ALMDevOpsCenterHub`.
   - **Deploy mode:** run the environment lookup (`list-orgs.md`) using the org's **URL, org id, or local alias only**, never the environment name the user wants to give it. If `sourceMatched` is `true`, say it cannot be connected as its own deploy target and ask for another org. If a row matches, check its `NamedCredential`. A row that matches only by name belongs to another org: that name is taken, so ask for a different one. If the user gave no URL, org id, or alias, there is nothing to match: create.

| Finding | Action |
|---|---|
| Exists, principal `Configured`, callout URL is the real org (not a login host) | Stop. Already connected; return to the calling flow with the NC name. **Hub, asked for directly by the user:** reply only "The Lifecycle Center org is already configured." with no reconnect offer, org details, or login link. |
| Exists but `NotConfigured`, or callout URL is still a login host | Repair. **Hub:** re-run Steps 1–4 with the same name (POST is idempotent). **Deploy:** reuse the existing row's `Id`; do **not** POST a second environment. Confirm first: "I'll reconnect `<name>`: this refreshes its credential. Proceed?" Then get a fresh login URL with `GET /connect/devops/environment/<id>` (its `redirectUrl`) and go to Step 2. |
| Matched row is `expired` | Not repairable. Create a new environment (Steps 1–4) with a new name. |
| `ambiguous` | Show the matches and ask which one. |
| Does not exist | Create. Run Steps 1–4. |

## Step 1 — Create the credential and get the login URL (POST)

**This creates metadata in the dev org. Confirm with the user first:**

> "I'll connect `<name>` (`<type>`) to DX Inspector in `<dev-org-alias>`: this creates the environment record and its credential. Proceed?"

**Hub mode** has no environment record. Say instead: "I'll connect the Lifecycle Center org to `<dev-org-alias>`: this creates its credential. Proceed?" For a repair, add that a failed finish step clears their saved DX Inspector selections.

**Deploy mode** — Environment API (creates NC, EC, and the `DevopsEnvironment` row):

```bash
sf api request rest "/services/data/v<ver>/connect/devops/environment" \
  --method POST \
  --body '{"envName":"<name>","orgType":"<PRODUCTION|SANDBOX|ORGFARM>","isDevEnv":false}' \
  --target-org "<dev-org-alias>"
```

Response: `{id, name, namedCredential, redirectUrl, orgType, ...}`. Keep `id` (the `DevopsEnvironment` Id) and `namedCredential`. Send only `envName`, `orgType`, and `isDevEnv`. A `BAD_REQUEST` naming `Invalid org type` means the value above was wrong.

**Hub mode** — `setupNamedCredential`:

```bash
sf api request rest "/services/data/v<ver>/connect/devops/setupNamedCredential" \
  --method POST \
  --body '{"namedCredentialName":"ALMDevOpsCenterHub","namedCredentialType":"ORG_TO_ORG"}' \
  --target-org "<dev-org-alias>"
```

Response: `{"redirectUrl": "..."}`. In both modes replace every `&amp;` in `redirectUrl` with `&`.

The server **swallows setup errors** and can still return an empty `redirectUrl`. If it is empty, stop and diagnose with `troubleshooting.md`. Do not continue to the PATCH. In deploy mode an environment row may already exist; tell the user and offer to delete it with `DELETE /connect/devops/environment/<id>` (removes the NC/EC too) after confirmation.

## Step 2 — User completes the OAuth login via a link

This step **requires a human** (authorization code with PKCE, stored per user). The CLI cannot open the user's browser from a chat, so **do not claim a browser was opened** and do not run `sf org open`. Show the sign-in as a button-style link, using exactly this layout (deploy mode shown; `<name>` is the environment name):

> **Connect `<name>`**
>
> **[Sign in to `<name>` →]({{redirectUrl}})**
>
> 1. Sign in with the user DX Inspector should act as, and approve access.
> 2. Come back here and reply **done**.
>
> Link not working? Copy it: `<redirectUrl>`

Hub mode uses the heading **Connect the Lifecycle Center org** and the link text **Connect to Lifecycle Center org**.

Rules for the link:
- Use the full `redirectUrl` after the `&amp;` fix, unmodified, as the Markdown link, and again in the "Link not working?" line. Show the sign-in once; do not repeat it in other words.
- Only the newest link works. Each new Step 1 run (hub) or `GET /connect/devops/environment/<id>` (deploy) replaces the previous one, so never run one while the user is still signing in, and never show an older link again. If the user reports it expired or failed, get a fresh one the same way.
- The user should open it in a browser that is signed in to the dev org as the same user the CLI uses (the final confirmation happens on the dev org). Otherwise the browser lands on that org's login page: tell them to sign in there, then use the link again.
- Right after showing the layout, wait for the user to reply **done**. Do not run other steps in between.

**Hub mode:** the user must log in as someone holding the **DevOps Center User** permission set in the hub org.

## Step 3 — Confirm the OAuth token landed

When the user says they are done, check the EC principal (`connect-api.md`, *Check credential status*).

| Status | Action |
|---|---|
| `Configured` | Go to Step 4. |
| `NotConfigured` | The login did not complete. Ask whether they saw an error and offer to re-run Step 1 for a fresh URL. Do not PATCH. |

## Step 4 — Finalize: set the real org URL (PATCH)

The NC is created pointing at a placeholder login host. The PATCH calls `/services/oauth2/userinfo` through the NC, rewrites the callout URL to the real My Domain, and (deploy mode) stores the target's org id and URL on the `DevopsEnvironment` row. Until it succeeds, callouts go to the wrong host.

**Deploy mode:**

```bash
sf api request rest "/services/data/v<ver>/connect/devops/environment/<id>?registerWorkspaceAlias=true" \
  --method PATCH --body '{}' --target-org "<dev-org-alias>"
```

`registerWorkspaceAlias=true` makes Core also register the environment name (the name the user chose) as an org alias in this workspace, next to `default-org`, so `sf ... --target-org "<name>"` works here. Core reads the token itself; the token never comes back in the response. This is best effort: if no workspace is running or the registration fails, the PATCH still succeeds and the response is unchanged. The CLI rejects a PATCH with no body, so keep `--body '{}'`. On an org below API `68.0` drop the query string (and still send `--body '{}'`); the connect completes without an alias. Send the flag only on this connect PATCH, never in hub mode.

Success returns `id`, `organizationId`, `orgUrl`, `status`, and `message`. Keep `namedCredential` from the POST. Verify `orgUrl` is a My Domain URL and **not** `login.salesforce.com` or `test.salesforce.com`.

Core names the alias after the environment (trimmed). It skips a blank name and `default-org`, and, in the Core build checked so far, a name with spaces (the environment itself still connects; only the alias is skipped until Core accepts spaced names); Core has no other rule for the alias: digits and hyphens are allowed. Only the credential name keeps just the letters of the environment name. If the local workspace gate is closed, Core registers through the remote workspace instead; the result is the same alias.

The alias is for the user's convenience in the workspace. It does not change how targets are chosen (see the rules in `SKILL.md`). The workspace token expires after about an hour. If an `sf` command with the alias fails on auth, repeat this same PATCH once to refresh it.

**Hub mode:**

```bash
sf api request rest "/services/data/v<ver>/connect/devops/setupNamedCredential" \
  --method PATCH \
  --body '{"namedCredentialName":"ALMDevOpsCenterHub","namedCredentialType":"ORG_TO_ORG"}' \
  --target-org "<dev-org-alias>"
```

Success returns `{"namedCredentialName": "...", "calloutUrl": "https://<org>.my.salesforce.com", "redirectUrl": null}`. Verify `calloutUrl` the same way.

- On failure (`DOCE_CONNECTION_UPDATE_FAILED`, a 404, a userinfo failure, or `TARGET_ORG_*` codes) see `troubleshooting.md`. A `TARGET_ORG_AUTHENTICATION_TIMEOUT` is transient: wait about 10 seconds and PATCH once more, and do not give a new sign-in link for it.
- **Never retry the PATCH in a loop.** **Hub mode only:** a failed PATCH also **clears the user's saved DX Inspector selections**. Tell the user.

## Step 5 — Verify and hand off

1. Re-run the status check. Expect principal `Configured` and a callout URL equal to the PATCH `calloutUrl`.
   **Deploy mode:** also check the alias with `bash scripts/resolve-environment.sh "<dev-org-alias>" "<name>"` and read `match.readiness` (never `sf org display`, which prints the token). Registration runs in the background after the PATCH returns, so if it is `needs-sync` wait about 5 seconds and check once more. If it is still `needs-sync`, tell the user the org is connected but the workspace alias is not available yet, and offer to repeat the PATCH once. `ready` or `unverified`: say nothing about the alias.
2. **Hub mode only:** optionally record the hub type the way DX Inspector does. A `CORE` or `MANAGED_PACKAGE` response proves the NC works end to end.

   ```bash
   sf api request rest "/services/data/v<ver>/connect/devops/doceConnectionType" --target-org "<dev-org-alias>"
   ```

3. Show the result with exactly this layout, no raw JSON, and never the credential name.

   Deploy mode:

   > **✅ `<name>` is connected**
   >
   > | Org | Type | Status |
   > |---|---|---|
   > | `<host of orgUrl>` | Sandbox, Production, or OrgFarm | Ready to deploy to |

   Hub mode (use the `calloutUrl` host; leave out the Hub type column when the type call was skipped or unknown):

   > **✅ The Lifecycle Center org is connected**
   >
   > | Org | Hub type | Status |
   > |---|---|---|
   > | `<host of calloutUrl>` | Core or Managed package | Connected |

   Say "Sandbox" for a scratch org too. If the status check in item 1 did not return `Configured`, do not show this layout: say the sign-in is not complete and offer a fresh link.
4. **Deploy mode:** re-run the environment lookup (`list-orgs.md`) and confirm the row with the `id` from Step 1 is listed, `selectable`, with its `NamedCredential`. Carry that `id` and `namedCredential` forward. If it is missing, do not deploy and do not invent an id; report that the credential is connected but the row was not found.
5. **If this connect started from a deploy request** (`deploy.md`, Step 2): tell the user in one sentence that `<name>` is connected and that you are continuing the deploy of the components they gave. Then go to `deploy.md`, Step 3 and Step 4. The deploy confirmation is theirs to give; do not submit anything before it. If the connect did not start from a deploy, end here and do not offer anything beyond the result.

---

## Sync workspace access (alias only)

Registers or refreshes the environment's workspace CLI alias without a sign-in. Use it when the user clicks a **Sync**, **Refresh**, or **Re-sync** button (`list-orgs.md`), asks for CLI access to a connected org, or an `sf ... --target-org "<alias>"` command fails with `Session expired or invalid`. It is the same PATCH as Step 4 and never creates an environment.

**Why it is needed.** Core registers the alias only when the connect PATCH runs with `registerWorkspaceAlias=true` against a **running** workspace. So an org connected in **DX Inspector** (the Lifecycle Center UI) has a row and a credential but no alias here; an org connected in Builder Central chat has both. Alias tokens also expire after about an hour.

1. **Find the row.** Run `bash scripts/resolve-environment.sh "<dev-org-alias>" "<name-or-alias>"`. For a failed command, pass the alias from the command. Use `match` only when `matchStatus` is `matched`.
   - No match (`not-connected`): the alias is not a DX Inspector environment. Do **not** PATCH anything. Offer to connect it (`connect-org.md`, Step 0).
   - `state` is `expired`: retired, not repairable. `unauthenticated`: repair path (fresh sign-in link), not a sync.
   - `readiness` is `needs-my-signin` (`userAuth: notConfigured`): another user connected this environment and this user has not signed in. Do not sync. Use the repair path (fresh link from `GET /connect/devops/environment/<id>` `redirectUrl`, login **as this user**, PATCH once with `registerWorkspaceAlias=true`), then rebuild the list.
   - `readiness` is `alias-conflict`: stop; the name belongs to another org (`troubleshooting.md`).
   - Otherwise take `match.id`. A button click or the user's explicit ask is the confirmation, so do not ask again.
2. **PATCH once.**

   ```bash
   sf api request rest "/services/data/v<ver>/connect/devops/environment/<id>?registerWorkspaceAlias=true" \
     --method PATCH --body '{}' --target-org "<dev-org-alias>"
   ```

   On an org below API `68.0` drop the query string; the alias cannot be registered there, so say so and stop.
3. **Read the outcome.**

   | Result | Do |
   |---|---|
   | Success | Go to step 4. |
   | `TARGET_ORG_AUTHENTICATION_TIMEOUT` (408/504) | Transient: the org did not answer in time. Wait about 10 seconds and PATCH **once more**. If it times out again, stop: "`<name>` didn't respond in time. Try again in a few minutes." Do **not** show a sign-in link and do not call the credential stale. |
   | `TARGET_ORG_AUTHENTICATION_STATUS_CHECK_FAILED` (401/403) | The DX Inspector credential is stale or revoked. Repair path: fresh sign-in link, login, then PATCH once. |
   | `TARGET_ORG_UNKNOWN_ERROR` | Report the plain-language cause (for example "Environment record not found" means the id is wrong; "does not have a named credential" means the connect never finished and needs repair). Stop. |
4. **Verify.** The alias is registered in the background after the PATCH returns, and a failure there is swallowed, so the response proves nothing about it. Wait about 5 seconds, run the resolver again, and read `readiness` for that row.

   | `readiness` | Say |
   |---|---|
   | `ready` or `unverified` | Nothing about the alias beyond "`<name>` is ready in this workspace." |
   | `needs-sync` | Repeat step 2 **once**. If still `needs-sync`: "`<name>` is connected and deploys work, but its CLI alias isn't available in this workspace. Registration needs a running workspace and the feature enabled for this org." Stop; never loop. |
   | `alias-conflict` | Stop; explain the name clash. |

   Registration targets the user's **already running** workspace only; it never starts one. If the CLI runs in a different workspace from the running one, the alias lands in the running one: tell the user which if they report it missing.
5. **Retry the command** that triggered a failed-command sync, once, **without asking**. The same applies when a task needs CLI access to an org whose `readiness` is `needs-sync` or `needs-refresh`: run steps 1 to 4 first, then the task. Listing alone still does not sync. If it fails the same way, report it and stop. Never retry with another org's alias or `default-org`.
6. **Batch** (`Sync all N`): run steps 1 to 4 for each row, one at a time, then report one line each (synced, timed out, sign-in needed, name clash, not available). Stop a row's retries independently; one failure does not stop the others.
7. **Show the list again** (`list-orgs.md`, section 4) so the user sees the result.

## Rules

- Never fabricate an NC name, callout URL, or `Configured` status. Report only what the org returned.
- Never print access tokens, and never pass `headerTargetAccessToken` in place of a stored connection.
- One environment per target org. Do not reuse a deploy NC for a different org; create a new environment.
- Deploy-target connections always use the Environment API so the `DevopsEnvironment` row exists. Never use `setupNamedCredential` alone for a deploy target.
- Never tell the user a browser was opened. Show the sign-in as in Step 2.
- Do not rename `ALMDevOpsCenterHub`. DX Inspector looks it up by that exact name.
- Only the org-to-org types (`ORG_TO_ORG`, `ORG_TO_SANDBOX_ORG`, `ORG_TO_ORGFARM_ORG`) are used here.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall