alchemy-pinned-exact

"alchemy": "^2.0.0-beta.79"  // ❌ the next lockfile refresh can pull a breaking beta
"alchemy": "catalog:"        // ❌ when pnpm-workspace.yaml has `alchemy: ~2.0.0-beta.79`
"alchemy": "2.0.0-beta.79"   // ✅ also through `catalog:` / `catalog:<name>` resolving to it

Betas break without a major bump: 2.0.0-beta.78 made every non-interactive alchemy deploy under bun crash in the CLI renderer (alchemy#1689). Reads dependencies, devDependencies, and optionalDependencies of the root manifest and every member of pnpm-workspace.yaml packages or package.json workspaces. A range whose lower bound is a stable 1.0+ release stays silent. workspace:, file:, link:, and git specs → ⚠️ unsupported. A catalog: with no matching entry → ❌ failed. The lockfile is not read.

alchemy-state-gitignored

# apps/api/alchemy.run.ts
dist/            # ❌ apps/api/.alchemy/ is not ignored
.alchemy/        # ✅ root or apps/api/.gitignore; `.alchemy`, `.alchemy/*`, `**/.alchemy` work too

localState() writes .alchemy/state/<stack>/<stage>/*.json, resource outputs included, under the CLI's working directory. The probe is <stack dir>/.alchemy/state/. Inside a git work tree it asks git check-ignore --no-index, so every rule git applies counts, then rejects matches from .git/info/exclude or a global excludes file: teammates don't share them. git ls-files also fails state that is already committed. Without git (not a work tree, no git binary), it reads the .gitignore files from root down to the stack directory with git's pattern rules; files above root are not read. A --config stack run from another directory writes .alchemy/ there, which this check does not follow.

ci-uses-remote-state

state: localState(),                                          // ❌ with any CI `alchemy deploy`/`destroy` of this stack
state: Cloudflare.state(),                                    // ✅ also AWS.state(), postgresState()
state: process.env.CI ? Cloudflare.state() : localState(),    // ⚠️ warns: confirm CI takes the remote branch

A CI runner discards .alchemy/state with the job: the next deploy starts from empty state and collides with live resources, and a destroy plans nothing and leaks them. Finds alchemy <command> in every run: step: bare, npx/bunx/pnpx, pnpm [exec|dlx], yarn [dlx], bun [x|run], npm exec, with cd <dir> &&, working-directory and defaults.run. Package scripts (pnpm ship, npm run ship, bun run ship, yarn ship) are read from the nearest package.json and followed two levels deep, with forwarded arguments appended (bun run deploy --stage pr-1; npm only after --). Package selection resolves -C/--dir/--prefix/--cwd, -w/--workspace, -ws, -r, yarn workspace <name>, and --filter/-F by name or path glob. Anything else that runs a script is reported as unsupported, never dropped: a directory from ${{ matrix.* }} or $VAR, --filter graph selectors (pkg..., !pkg, {dir}), yarn workspaces foreach, a third nested script, an unreadable package.json. deploy --dry-run counts as a plan. The stack file is <cwd>/<--config or positional or alchemy.run.ts>, parsed with oxc: state: in Stack(...), Alchemy.Stack(...), or Stack.make(...), store constructors recognized only through their alchemy, alchemy/State, alchemy/Cloudflare, alchemy/AWS imports, top-level consts followed. A workflow with no Alchemy command passes: there is nothing to lose.

preview-cleanup

- run: alchemy deploy --stage pr-${{ github.event.number }} # ❌ alone: every closed PR leaves resources running
# ✅ plus, in a workflow on `pull_request: types: [closed]`:
- run: alchemy destroy --stage pr-${{ github.event.number }}
- run: alchemy destroy --stage prod # ❌ never destroy production from CI

The stage is --stage, else ALCHEMY_STAGE, with ${{ env.X }}, $X, ${X} substituted from workflow, job, and step env (twice, so a job value reading the workflow env resolves). A stage containing pr- is a preview, which covers the shared STAGE: ${{ ... format('pr-{0}', ...) || 'prod' }} pattern of the Alchemy CI guide. The destroy must target the same stack file, unless either side's directory is dynamic. A destroy whose stage is literally prod / production fails; one whose expression contains either word fails unless a step of the same job, up to the destroy, runs exit 1 and names either production (the guide's deny check) or pr- (an allow-list like case "$STAGE" in pr-*) ;; *) exit 1;; esac); the guard's condition is not evaluated. An unresolved script in a closed workflow turns a missing cleanup into ⚠️ unsupported, since that script may be the destroy. A branch literally named prod reaching github.ref_name is invisible to this literal check.