Keep builds out of the CI deploy job, keep its token out of the checkout, and pin the CLI

[dawsontoth]

⊙ Problem

The CI guide's workflows, which HarperFast/skills#119 quotes word for word, had three gaps:

• Path A's checkout left the job's token in .git/config.
• Path A installed harper unpinned, so rerunning an old tag after a new major release would change the CLI.
• Path B built in the job with id-token: write. A compromised dependency could request a token and trade it for the deploy user's Harper token.

🤔 Fix the docs rather than the skill?

Yes. The skill rule is generated from this page, so a skill-only fix would be undone by the next sync.

💡 Solution

• Path A's checkout sets persist-credentials: false, and every workflow installs harper@^5.3, the first CLI with OIDC.
• Path B is two jobs. publish builds and publishes without id-token; deploy holds it and installs only the CLI. The page says this narrows the risk but doesn't remove it.
• The reference pages say to build outside the deploying job.

🤔 Is losing ref=<tag> in private repositories acceptable?

With the token kept out, the CLI can't look a tag up on GitHub, so the page now says to pass a full commit SHA, or fetch tags with fetch-depth: 0. The alternative keeps the token in the job for that one lookup.

⚖️ Alternatives

• An exact pin (harper@5.3.2) — every page and template would need updating per release. ^5.3 keeps a rerun on 5.x, but each new 5.x installs in the job that can request a token.
• Raising the wait loop's 60 polls — left as is; the page now says it gives up after about ten minutes, and to raise the count on a large cluster.

🤔 Should Path B publish before an approval?

With required reviewers on production, the package now publishes before anyone approves, since the approval gates only deploy. Gating publish too would need a second approval, or a second environment.

🔧 Changes

• learn/developers/deploying-from-ci.mdx: Path A's checkout and CLI pin, with a bullet for the checkout and one for the pin; its job runs no repository code; the ref= caveat; the wait-loop limit. Path B's two jobs, why, the risk they leave, and the credential and scope notes now naming publish and no longer the CLI. The preview workflow's CLI pin.
• reference/cli/authentication.md: why the example job runs no repository code, and where a build belongs.
• reference/operations-api/operations.md: add_oidc_trust's overview says the deploying job needs id-token: write, and to build elsewhere.

✅ Verification

• npm run build passes with no broken-link or anchor warnings, and npm run format:check is clean.
• The page's three workflow blocks parse as YAML. In Path B, publish holds contents: read and packages: write only, and deploy holds id-token: write only.
• npm view 'harper@^5.3' version resolves to 5.3.2.
• The ref= caveat is traced in the CLI: with GITHUB_SHA set, by_ref=true needs no git lookup, while a tag missing from the checkout goes to git ls-remote.

Related: HarperFast/create-harper#151 (the same fix in the Next.js templates), HarperFast/skills#119 (the rule that quotes this page; its npm install -g harper anchor is updated to match).

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

Related PRs: #722 overlaps (merged; added the reference example whose checkout and pin this carries into the guide)
Complexity: medium

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; blocked=cursor-composer(no-receipt); declined=cursor-grok,cursor-kimi,cursor-muse,muse; rounds=2; full=1 @ c8f6245}

_{Review-Attention: skim ~2m (decisions: caret-range-cli-in-token-job, publish-before-approval, path-a-single-job) @ c8f6245}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-731

This preview will update automatically when you push new commits.

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.