deploying-to-harper-fabric: deploy from CI with OIDC, and go back by deployment_id #117

Part of HarperFast/create-harper#143.

Problem

Agents in a Harper project learn how to deploy from harper-best-practices, which create-harper installs into every new project. Its deploying-to-harper-fabric rule is generated from the docs. rules.manifest.yaml sources it from:

• reference/v5/components/applications.md, section "Remote Management";
• fabric/cluster-creation-management.md, section "Connecting the Harper CLI to a Cluster".

Those sections describe deploys before 5.3, and so does the rule:

• CI authentication. CI authenticates with HARPER_CLI_USERNAME and HARPER_CLI_PASSWORD, and the example uses admin/secret. Since Harper 5.3.0, a GitHub Actions run can deploy with no stored credential, through OIDC trusted publishing, as a role that can only deploy.
• Rolling back. It says "Roll back by deploying an older commit" (harper deploy ref=<sha>). Since 5.3.0, each node keeps the releases a deploy replaced, and activating a deployment_id goes back to one with nothing to rebuild.
• Restarts. It uses restart=true replicated=true everywhere. It says nothing about:
  • canary certification (5.4.0);
  • the certification field in the response;
  • waiting for a rolling deploy's job.
• Staging and history. It says nothing about staging (activate=false) or list_deployments.

The synthesized creating-harper-apps rule ends with "Use npm run deploy". It says nothing about the deploy workflow create-harper is about to scaffold (HarperFast/create-harper#144, HarperFast/create-harper#145).

Proposal

1. Widen the deploy rule's sources, once the docs are fixed (Deploying from CI: lead with OIDC, and correct the deploy reference where it disagrees with Harper documentation#711). Add:

   • reference/v5/cli/authentication.md, section "Workload identity (OIDC)";
   • reference/v5/operations-api/operations.md, sections "Going back to a previous release", "Certifying a release in a canary worker" and add_oidc_trust;
   • learn/developers/deploying-from-ci.mdx, once it's rewritten around OIDC.

   Alternatively, give CI its own generated rule (deploying-from-ci), so deploying-to-harper-fabric stays about a manual deploy.

2. Pin the new facts in must_cover so they survive regeneration: id-token: write, add_oidc_trust, deployment_id, certification and get_job. Also revisit the existing PAT anchors (fine-grained, Contents: Read-only, read:org, enc:v1:, refs/tags). They assume deploying by reference is the main path, and they will fail if the docs move that guidance.

3. Update creating-harper-apps once Deploy on merge to main with GitHub OIDC instead of a stored refresh token create-harper#144 and #145 land. It should cover:

   • merging to main deploys;
   • npm run deploy:setup-ci runs once;
   • npm run deploy is for a manual deploy.

4. Regenerate, rebuild AGENTS.md, and release.

Blocked by

Auto-sync has failed on every docs deploy since 2026-09-14 (#118, which consolidates #91–#116). The latest run (docs 2cfb813, run 37484111044) fails validate-generated, because regeneration drops facts from four other rules:

• schema-design-tooling
• automatic-apis
• querying-rest-apis
• v5-upgrade

Until that's fixed, no docs change reaches any rule. Either fix the sync first, or regenerate this rule locally with npm run generate -- --docs-path <docs>.

Related

• deploying-to-harper-fabric: Document .env deployment behavior, env namespacing, verification, and static file caching #20 asks for more in the same rule: .env behavior, env namespacing, verification and static file caching.

Done when

In a project with these skills:

• An agent asked to set up deploys from GitHub sets up OIDC, with no stored credential.
• An agent asked to roll back activates a deployment_id instead of redeploying an older commit.