feat(harper-best-practices): deploy from CI with OIDC, and roll back by deployment_id

[dawsontoth]

⊙ Problem

harper-best-practices taught deploys from before Harper 5.3: CI signed in with a stored username and password, and nothing mentioned the deploy workflow create-harper now scaffolds. Given only the skill, an agent on main writes a deploy workflow it can't authenticate, or keeps a refresh token in a GitHub secret.

💡 Solution

Deploy guidance is now two rules generated from documentation@81c1b0e. deploying-from-ci leads with harper deploy setup=true provider=github-actions (HarperFast/harper#3127), which sets up OIDC trusted publishing in one command, and keeps the hand-written policy for tag releases. deploying-to-harper-fabric covers restart modes, canary certification, staging, and going back by deployment_id. creating-harper-apps covers create-harper's scaffolded workflow and deploy:setup-ci (HarperFast/create-harper#147). Closes #117.

This is meant to merge before Harper 5.4.0, which ships the setup command, is published. Until then, the rules send earlier versions to the hand-written route, with commands for the scaffolded workflow.

⚖️ Alternatives

• One wider deploy rule, as deploying-to-harper-fabric: deploy from CI with OIDC, and go back by deployment_id #117 proposed first: its input would be ~65KB, against ~31KB and ~35KB for the two halves, and regeneration compresses away more facts the larger the input.
• Generating the bodies with npm run generate: there's no ANTHROPIC_API_KEY here, so they're hand-written to the generator's template with real input hashes, as you OK'd. sync:report lists both as current, and the next regeneration resamples them.

More for the reviewer

• Sources. The CI rule starts from the setup command's reference section, then sources the rewritten guide. It leaves out the guide's isolated-worker and per-PR preview sections, ~18KB and a different task. The guide's "Other CI systems" section isn't sourced, so the rule covers GitHub Actions only.
• The CI rule's one complete workflow is the docs' tag-triggered Path A, while setup and create-harper deploy on merge to main. The rule shows the single job a merge-to-main deploy needs; a complete one would have to come from the docs first.
• CI defaults to restart=rolling plus a 10-minute get_job wait, as the guide and create-harper's workflow do. A job lives only on the node that received the deploy, so polls a load balancer routes elsewhere fail the step after a deploy that succeeded. The rule gives the docs' remedy: one node's URL for the deploy, the wait and the audience.
• The PAT anchors stay. Deploying a private repository by reference still needs that credential; their comment says to re-point the source if the docs move it.
• This supersedes the deploying-to-harper-fabric bodies docs: regenerate rules from documentation@2cfb813 #121's and docs: regenerate rules from documentation@e73e5ef #122's syncs regenerated from the old sources, and keeps every fact of the latest that the docs still have.

🔧 Changes

• harper-best-practices/rules.manifest.yaml:
  • deploying-to-harper-fabric gets a new description and eight new sources, by section: the harper deploy parameters, the CLI's operation syntax, four deploy_component subsections (canary certification, staging, going back, and retrying an activation), list_deployments and get_job. Restarting is left out. New anchors pin going back by deployment_id, replicated=false, and the certification table and the rolling-job wait.
  • deploying-from-ci is new: the setup command's reference section, six sections of the CI guide, plus workload identity, GitHub Actions policy specificity, list_oidc_trust and drop_oidc_trust. Its anchors hold the setup command, workflow=, its policy name and registration_info, Path A's trigger and jobs: wrapper, the environment gate, the deploy-only role, load-balanced polling, diagnosing and revoking, and the user setup creates.
  • The later ops rules shift down one order to make room.
• harper-best-practices/rules/deploying-to-harper-fabric.md: rewritten from the wider sources at 81c1b0e. It covers logging in, and pointing GitHub Actions at the setup command, default replication on Pro and Fabric, restart modes and certification, polling the node that received the deploy, going back by deployment_id, with a rolling restart in its operation form too, and staging, including what retrying an activation does on each node. Package sources, deploying by reference and private-repository credentials are kept, with a pointer from setup=true to the CI rule, and the examples include a rolling rollback.
• harper-best-practices/rules/deploying-from-ci.md: new. It covers the one-command setup: its defaults and workflow=, what it checks, creates and refuses, and when the policy has to be written by hand. Then how a job's harper commands authenticate, with the four conditions and a single deploy job; the hand-written role and user, now with registration_info; the trust policy and its environment gate; private-source credentials, Path A's workflow, Path B, diagnosing a refused run, the deployment record, and rollback, rotation and revocation. Examples give the setup for a deploy.yml workflow, replacing the policy setup wrote, the hand-written setup, a push-to-main policy and an incident revocation.
• harper-best-practices/rules/creating-a-fabric-account-and-cluster.md: step 6 now runs harper login and sets HARPER_CLI_TARGET instead of a username and password in .env, and sends CI to deploying-from-ci rather than GitHub secrets. fix(templates): set HARPER_CLI_TARGET in the scaffolded .env create-harper#146 switched the scaffolded .env to the same name.
• harper-best-practices/rules/creating-harper-apps.md: Next Steps log in and set HARPER_CLI_TARGET instead of putting credentials in .env, and a new Deploying section covers the scaffolded deploy.yaml: deploy:setup-ci once, the by-hand setup before 5.4.0, merging to deploy, npm run deploy by hand, going back by deployment_id, and moving an older project over.
• harper-best-practices/SKILL.md and harper-best-practices/AGENTS.md are regenerated from the manifest and rule bodies: the index gets the new descriptions, and AGENTS.md gets 4.1, the new 4.2, the changed 4.3 and 4.4, with the later ops sections renumbered.

Reviewers flagged three points in the workflows the CI rule quotes from the docs: Path A's persisted checkout token, its unpinned harper install, and Path B building in the job that holds id-token: write, which create-harper's Next.js workflow also does. A fix here would be regenerated away, so HarperFast/documentation#731 and HarperFast/create-harper#151 fix them at the source, and the rule picks them up on the next sync. #731 drops npm install -g harper from the sourced sections, so the anchor is now npm install --global harper@^5.3, and Path A's quote matches #731's checkout and install. Validate passes whichever PR merges first.

✅ Verification

Agents given only the skill, on main and on this branch, answered three deploy requests. On this branch they ran the setup command (with workflow= for a deploy.yml), npm run deploy:setup-ci for a scaffolded project, and the hand-written policy for v* tags, storing no secrets. On main they wrote workflows with no way to authenticate. The setup command itself wasn't run, because 5.4.0 isn't published.

Agent answers, smoke test and checks

• Agents. Sonnet agents, each told to read only a copy of the skill and answer three requests:

  Request	Skill from main	Skill from this branch
  "Set up automatic deploys to our Fabric cluster from GitHub Actions whenever we merge to main" (repository not from create-harper, workflow file deploy.yml)	A workflow with id-token: write and no trust policy or deploy user ("details not in skill"); else a harper login --for-ci token kept as a GitHub secret	harper deploy setup=true provider=github-actions project=my-app workflow=.github/workflows/deploy.yml, with json=true and the wait step in the job; no secrets
  "I just scaffolded this project with npm create harper@latest. How do I get it deploying to my Fabric cluster?"	npm run deploy from the machine, optionally with CLI_TARGET_USERNAME/CLI_TARGET_PASSWORD in .env; doesn't know the project has a workflow	Push to GitHub, run npm run deploy:setup-ci once (5.4.0), then merge to main; npm run deploy by hand, going back by deployment_id
  "We cut releases by pushing v* tags. Set up GitHub Actions to deploy each tag"	A tag workflow running harper deploy ref=${{ github.ref_name }}, with authentication left open	The hand-written role (with registration_info) and a workflow_path policy gated on the production environment, restricted to v* tags; Path A's workflow with its wait step

• Live smoke test, on a throwaway Harper 5.3.1, of the hand-written route's commands (run against an earlier revision of the rules; the role now also lists get_deployment and registration_info):

  • add_role with an operations list, add_user, add_oidc_trust with claims (both a workflow_ref policy and a tag-release workflow_path one), list_oidc_trust, drop_oidc_trust, and alter_user active=false. After the last, list_oidc_trust reported invalid_reason: names inactive user 'ci-deploy'. An audience without a port was rejected as the rules say.
  • v1 and v2 deployed with restart=true each returned a deployment_id, list_deployments listed them, and harper deploy project=my-app deployment_id=<v1> restart=true served v1 again. A payload staged with activate=false left v1 serving until its id was activated, and restart with activate=false was refused.
  • harper get_job id=<restartJobId> reported IN_PROGRESS, then ERROR: single-node core can't run a rolling restart ("Replication not implemented"), as the guide says. A real OIDC exchange from GitHub and canary certification (5.4.0) were not exercised.

• npm run validate passes: format, build, tests, both validators, and the relationship lint.

• node scripts/generation/validate-generated.mjs --docs-path <documentation@81c1b0e> passes, fact retention and every must_cover anchor included, and npm run sync:report lists both deploy rules as current with 81c1b0e. It lists load-env as stale from unrelated docs changes; docs: regenerate rules from documentation@356a3bf #123 regenerates it.

🤖 Generated with Claude Code

Related PRs: #122 supersedes (its deploying-to-harper-fabric body, as with #121's before it), #120 independent
Complexity: medium

Deferred findings

• 3ff0dc941e775055 nit maintainability — harper-best-practices/rules.manifest.yaml — New manifest comments restate docs or identifiers instead of a minimal reason — NOT FILED

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

_{Review-Attention: study ~9m (decisions: do-less-alternative, fix-workflows-upstream, substring-anchors-for-yaml; raised: degraded review, open major) @ 638e8a1}

[github-actions]

🎉 This PR is included in version 1.15.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀