Deploying from CI: lead with OIDC, and correct the deploy reference where it disagrees with Harper

[dawsontoth]

Part of HarperFast/create-harper#143.

These are the gaps found while planning create-harper's deploy-on-merge workflow, checked against this repository at 2cfb813 and Harper main at be4009ca5 on 2026-10-06. Line numbers are from 2cfb813. No open issue or PR covers sections 1–3, 5 or 6. Some items were added or left by #707, #710 and #685, so they are recent.

1. The CI guide predates OIDC

learn/developers/deploying-from-ci.mdx was written in #594, before OIDC trusted publishing was documented in #637.

• Stored secrets. It authenticates with stored secrets, sent with curl (deploying-from-ci.mdx L91-107, deploying-from-ci.mdx L167-185): a super-user credential (HARPER_OPS_AUTH) and GitHub tokens (GH_DEPLOY_TOKEN, GH_PACKAGES_TOKEN).
• Tags only. It runs on v* tags only (deploying-from-ci.mdx L80-82, deploying-from-ci.mdx L140-142).
• Wrong version. It requires "Harper 5.2+" (deploying-from-ci.mdx L24), yet it describes canary certification (deploying-from-ci.mdx L114, deploying-from-ci.mdx L197, deploying-from-ci.mdx L222), which ships in 5.4.0. Date canary certification to 5.4.0, and add it to the 5.4 release notes #710 re-dated canary certification in operations.md, but not here.
• A wait step OIDC can't use. It waits for the rolling job with curl and HARPER_OPS_AUTH (deploying-from-ci.mdx L199-220). Under OIDC the operation token never leaves the CLI, so this step can't be used.

What to change:

• Lead with OIDC, using one complete workflow that runs as written:
  • on, jobs and runs-on, a checkout, and npm install -g harper;
  • permissions: id-token: write on the deploy job, plus environment;
  • vars.HARPER_CLI_TARGET;
  • harper deploy project=… restart=rolling json=true > deploy.json;
  • a wait that polls harper get_job. Progress goes to stderr (bin/deployRenderer.ts), so stdout stays parseable.
• Next to the workflow, show the trust policy and the deploy-only role. The role needs get_job (see section 2).
• Explain how to write the policy for a tag-triggered workflow: pin workflow_path and gate on environment, since workflow_ref can't pin a tag (operations.md L777).
• Keep the curl paths as the alternative for other CI systems. Use secret references instead of literal tokens, since a literal token needs super user (operations.md L742).
• Mark the canary text as 5.4.0+.

2. OIDC examples and roles

• The two OIDC examples are fragments. Both reference/cli/authentication.md (authentication.md L269-279) and operations.md (operations.md L623-632) put environment and steps at the top level, with no on, jobs or runs-on, and no CLI install. The first is even labelled .github/workflows/deploy.yml. They also disagree with each other: by_ref=true restart=true replicated=true against by_ref=true alone, which restarts nothing and so is never certified. Replace both with a link to the guide's workflow.

• The role and policy examples omit get_job. These examples list operations without it:

  • the role example (operations.md L730-742): ["deploy_component","get_deployment"];
  • the inline example (operations.md L688): the same list;
  • the scoped policy (operations.md L711): adds restart_service.

  But the guide's wait step polls get_job. An operations allowlist and a token's scope both refuse operations they don't list (utility/operation_authorization.ts, utility/operation_authorization.ts), so the wait step gets a 403. The jobs table's "Role Required: any" for get_job (operations.md L1912) hides this. restart_service isn't needed, because the rolling job is created internally.

• The CLI overview still recommends the refresh token. reference/cli/overview.md calls the refresh token "recommended for CI/CD" and doesn't mention workload identity (overview.md L161-168). That contradicts authentication.md (authentication.md L55).

3. harper deploy and the CLI reference

• Say that harper deploy restart=rolling exits 0 once the rolling job starts (commands.md L142), and give the CLI wait recipe. This stays true until harper deploy restart=rolling exits 0 before the other nodes have taken the release harper#3058 ships.
• Add activate=false and deployment_id= to harper deploy's parameters (commands.md L135-165). Note that restart can't be combined with activate=false.
• Fix where replicated is described as opt-in: commands.md L143, deploying-from-ci.mdx L113 and reference/components/applications.md (applications.md L348). On Harper Pro and Fabric, a deploy replicates unless you pass replicated: false. Core on its own doesn't replicate. Draft docs(learn): add Administration production reliability track #671 rewrites applications.md and operations.md around this.
• Fix the version for harper login and harper logout, which are dated v5.0.0 (commands.md L260, commands.md L298). They shipped in v5.1.0, as authentication.md L74 says.
• Fix the claim that harper login sets HARPER_CLI_TARGET in .env (authentication.md L151-155, overview.md L177, cluster-creation-management.md L62). It only appends to a .env that already exists and doesn't already set a target (bin/login.ts). commands.md L264 ("if it exists") is closest to right.
• Fix the install command npm i -g harperdb (overview.md L22). On npm that installs 4.7.39, which has no login, OIDC or by-reference deploys. Use npm install -g harper, as the getting-started guide does.

4. applications.md → Remote Management

This is the source of the deploying-to-harper-fabric skill, so it is what agents learn from.

• It recommends HARPER_CLI_USERNAME and HARPER_CLI_PASSWORD for CI/CD (applications.md L104-115). Point to workload identity instead.
• It says "Roll back by deploying an older commit" (applications.md L184). Since 5.3.0, going back means activating the kept release's deployment_id (Going back to a previous release). Keep ref=<sha> as the way to deploy a particular commit.

5. Deployment records (operations.md)

• deployment_id is a random UUID, not a content hash. operations.md L1208 calls it a "content hash", but each deploy gets a random UUID (components/deploymentRecorder.ts). The content hash is payload_hash.
• list_deployments has no default limit. operations.md L1179 says it defaults to 100, but leaving limit out returns every row (components/deploymentOperations.ts).
• The statuses are incomplete (operations.md L1211-1212):
  • loading, replicating and restarting occur while a deploy runs, so filtering on pending misses deploys in flight.
  • rolled_back and rollback_of are never written. Going back writes a new success record with activated_from, which operations.md L1221 describes only for staged builds.
  • A stage whose peers fail returns an error, but its record stays staged, with error set.
• Some fields are undocumented, and error is misdescribed. origin_node, restart_mode (immediate, rolling or null), credentials (references only) and payload_blob_present are returned but not documented. error is described as a message (operations.md L1223), but it's an object: { message, code, phase }.
• The record and "what is deployed" disagree for rolling deploys. With restart: 'rolling', the record says success before the other nodes take the release, and keeps saying it if one of them rejects the release. This stays true until A rolling deploy's record says success even when another node rejects the release harper#3060 ships. Reconcile it with the sentence recommending list_deployments for "what exactly is deployed right now".
• delete_deployment_payload also accepts staged. operations.md L1261 lists success, failed and rolled_back, and operations.md L959 already says a staged deployment works.

6. Streaming progress

• Document the SSE events. A streamed deploy_component sends phase, install, peer, warning, payload_dropped, error and done, with done carrying { result }. A replayed log can include truncated.
  • phase can also be pending, success or staged.
  • On 5.4, load brackets the canary's decision, so a deploy that doesn't restart no longer emits it (operations.md L1167, commands.md L131).
• The live tail only follows a deploy running on the node that answers. get_deployment's live tail (operations.md L1195) depends on this. Through a load balancer, it replays the log and returns, possibly with a status that isn't terminal.

Related

• deploying-to-harper-fabric: deploy from CI with OIDC, and go back by deployment_id skills#117 regenerates deploying-to-harper-fabric from these pages.
• harper deploy restart=rolling exits 0 before the other nodes have taken the release harper#3058, Report which deployment is live on each node, and which releases each node keeps harper#3059, A rolling deploy's record says success even when another node rejects the release harper#3060 and Record where a deploy came from: the commit, the CI run and the trust policy harper#3061 are Harper changes that some of these sentences will need to follow.
• These issues and PRs overlap:
  • Documentation: v5.1 release coverage #548, the v5.1 docs coverage umbrella, lists deployment tracking. Section 5 could sit under it.
  • Add Harper deploy behavior #478 covers harper deploy on CI runners.
  • Rename CLI commands from harperdb to harper #399 covers renaming harperdb commands to harper.
  • Draft docs(learn): add Administration production reliability track #671 covers the replicated default, and adds a safe-deployments-and-rollback page that should use deployment_id for going back.