Document `harper deploy setup=true provider=github-actions`, and how a workflow uses a trust policy by dawsontoth · Pull Request #722 · HarperFast/documentation

dawsontoth · 2026-10-09T01:56:29Z

⊙ Problem

HarperFast/harper#3127 adds harper deploy setup=true provider=github-actions, and nothing documents it. The docs also don't make plain how a workflow uses a trust policy once one exists. And they say registration_info returns registration details it hasn't returned since v5.0.0.

❓ Your call: is a "Using it in a workflow" section the right fix?

You asked that it be easy to see that every harper command in a set-up job authenticates by itself. It is one subsection that the operations reference and the CI guide link to, rather than the same text on each page.

💡 Solution

The CLI reference documents the setup command: what it creates, what it checks first, and that it only creates.
"Using it in a workflow" lists the four conditions under which harper deploy, or any other command, authenticates by itself, with a one-job example.
Every deploy role in the docs lists registration_info, and its entry says it returns only the version.

⚖️ Alternatives

Move the CI guide onto the setup command — the guide deploys on tags, and the command pins one branch, so the guide points at it in a tip instead.

❓ Your call: should every deploy role list `registration_info`?

harper deploy checks the version with it first. Without it the deploy still works, but the cluster logs a refused operation on every run. The cost is a deprecated operation in the guide's role and the policy examples.

🔧 Changes

reference/cli/commands.md: the GitHub Actions deploys (OIDC) section. It covers the default workflow name and workflow=, the repository lookup, the workflow check, the create-only variable, the policy-write race and recovery when the variable isn't set. The setup=true parameter mentions it.
reference/cli/authentication.md: the one-command setup, "Using it in a workflow", and an example role that lists registration_info.
reference/operations-api/operations.md: the OIDC section points at both. registration_info is corrected.
reference/cli/operations-api-commands.md: registration_info gets the Harper version.
learn/developers/deploying-from-ci.mdx: the same pointer, the tip, and the role.
release-notes/v5-lincoln/5.4.md: the new setup.

✅ Verification

npm run format:check and npm run build pass.
Each claim about the setup was checked against bin/deploySetupGithubActions.ts on Set up GitHub Actions deploys with harper deploy setup=true provider=github-actions harper#3127's branch. "Using it in a workflow" ran end to end there, with a mock OIDC issuer (see that PR).
registration_info's response was checked in resources/registrationDeprecated.ts at v5.0.0 and v5.3.2.

Depends-on: HarperFast/harper#3127

🤖 Generated with Claude Code

Related PRs: #713 overlaps, #728 overlaps (merged; its get_fingerprint and set_license wording was kept when merging main), 1 other independent
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex,cursor-muse; adjudicated=domain; declined=cursor-grok,cursor-kimi; rounds=6; full=2 @ 0c85d28}

_{Review-Attention: skim ~2m (decisions: setup-role-omits-get-deployment, document-policy-write-race, setup-branch-only-scope) @ 0c85d28}

…a workflow uses a trust policy - commands.md: a GitHub Actions deploys (OIDC) section for the new setup provider: what it checks and creates, that it only creates, its names, and how to revoke; `setup=true` mentions it - authentication.md: a "Using it in a workflow" subsection that says plainly that nothing in a workflow names the policy, and every `harper` command in a job authenticates through it when four conditions hold, with a one-job excerpt - operations.md and the CI guide point at both, and the guide notes the setup command suits branch-triggered workflows, not its tag-triggered ones - 5.4 release notes: the new setup Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

… looked up, and what the workflow check refuses Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

From the pre-push review: - the CI guide's :::tip closing marker sat on the paragraph's last line, so the admonition never closed; it now has a line of its own - "every harper command authenticates" now says each may do only what the policy's user's role allows, and the guide notes setup's role lacks the get_deployment the manual role adds - condition 4 lists every credential that outranks the exchange, and links the precedence order - commands.md says a missing workflow file leaves the whole check unverified, that a concurrent writer can still overwrite the policy, and what to do when setting the variable fails; every page names the role setup creates Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…say a rerun sets the variable again Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

gemini-code-assist

Code Review

This pull request updates the documentation across several files to introduce and explain the new GitHub Actions OIDC deployment setup (harper deploy setup=true provider=github-actions) added in version 5.4.0. The review feedback highlights multiple instances where the component is incorrectly used within running prose or mid-sentence, advising the use of plain text instead to maintain consistent formatting.

github-actions · 2026-10-09T01:59:49Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

…ge for headings Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-09T02:05:48Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

…turns - commands.md: the role `harper deploy setup=true provider=github-actions` creates now also allows registration_info (HarperFast/harper#3127). - deploying-from-ci.mdx and operations.md: the hand-written deploy role and policy scope list it too, since `harper deploy` checks the version with it first and an allowlist that omits it logs a denial on every deploy. - operations.md: registration_info returns only `{ version, deprecated }` (since v5.0.0), not registration status, RAM or license details. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

….4 note - operations.md: `get_fingerprint` no longer points at registration_info, which returns only the version. - operations-api-commands.md: registration_info gets the Harper version. - authentication.md: the example deploy role lists registration_info, like the role setup creates. - 5.4 release note: a rerun sets the variable again, and a policy another super user changes just before setup writes it is still overwritten. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-12T20:13:51Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

kriszyp

_{🤖 Reviewed with Codex}

Setup defaults to .github/workflows/deploy.yaml, create-harper's name, while the CI guide and the operations examples use deploy.yml. A missing default file is only reported as unverified, so setup could still pin deploy.yaml and leave a deploy.yml workflow's token unable to match. The reference now says so next to the command, with a workflow= example. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-13T00:07:51Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

…eckout rule Follows HarperFast/harper#3127's review changes: setup leaves a HARPER_CLI_TARGET that already names another cluster, requires a job in the environment to grant `id-token: write`, and checks the local workflow only when the checkout is the repository the policy is for. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Setup takes the checkout's repository from GITHUB_REPOSITORY before the origin remote, so the checkout rule now says both. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-13T00:49:51Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

Setup never writes a policy that already exists, so another super user's disable can't be overwritten; only a policy with the same id created in the moment before setup writes it can be (HarperFast/harper#3127). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-13T14:31:42Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

…hub-actions # Conflicts: # reference/cli/operations-api-commands.md # reference/operations-api/operations.md

github-actions · 2026-10-13T14:56:27Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

github-actions · 2026-10-13T20:42:12Z

🧹 Preview Cleanup

The preview deployment for this PR has been removed.

dawsontoth and others added 4 commits October 8, 2026 16:56

Match the setup steps to the final provider: the repository is always…

c9a6c60

… looked up, and what the workflow check refuses Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Qualify the release note's workflow check and create-only claim, and …

3bf4f3d

…say a rerun sets the variable again Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This was referenced Oct 9, 2026

Set up GitHub Actions deploys with harper deploy setup=true provider=github-actions HarperFast/harper#3127

Merged

feat: deploy on merge to main with GitHub OIDC instead of a stored refresh token HarperFast/create-harper#147

Merged

gemini-code-assist Bot reviewed Oct 9, 2026

View reviewed changes

Comment thread learn/developers/deploying-from-ci.mdx Outdated

Comment thread reference/cli/authentication.md Outdated

Comment thread reference/operations-api/operations.md Outdated

github-actions Bot temporarily deployed to pr-722 October 9, 2026 01:59 Inactive

Note v5.4.0 in plain text where it sits mid-sentence, keeping the bad…

3519a9a

…ge for headings Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions Bot temporarily deployed to pr-722 October 9, 2026 02:05 Inactive

dawsontoth marked this pull request as ready for review October 9, 2026 02:34

dawsontoth requested a review from a team as a code owner October 9, 2026 02:34

dawsontoth mentioned this pull request Oct 12, 2026

feat(harper-best-practices): deploy from CI with OIDC, and roll back by deployment_id HarperFast/skills#119

Draft

DavidCockerill mentioned this pull request Oct 12, 2026

Document model pricing, the agent's per-session spend caps, and final cancels #727

Draft

dawsontoth and others added 2 commits October 12, 2026 15:50

github-actions Bot temporarily deployed to pr-722 October 12, 2026 20:13 Inactive

dawsontoth mentioned this pull request Oct 12, 2026

Drop get_fingerprint and set_license from the v5 operation lists #728

Merged

kriszyp approved these changes Oct 12, 2026

View reviewed changes

Comment thread reference/cli/commands.md

github-actions Bot temporarily deployed to pr-722 October 13, 2026 00:07 Inactive

dawsontoth and others added 2 commits October 12, 2026 20:14

Say GITHUB_REPOSITORY, when set, names the checkout's repository

9f50073

Setup takes the checkout's repository from GITHUB_REPOSITORY before the origin remote, so the checkout rule now says both. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions Bot temporarily deployed to pr-722 October 13, 2026 00:49 Inactive

github-actions Bot temporarily deployed to pr-722 October 13, 2026 14:31 Inactive

Merge remote-tracking branch 'origin/main' into docs/deploy-setup-git…

0c85d28

…hub-actions # Conflicts: # reference/cli/operations-api-commands.md # reference/operations-api/operations.md

github-actions Bot temporarily deployed to pr-722 October 13, 2026 14:56 Inactive

DavidCockerill mentioned this pull request Oct 13, 2026

Document agent.maxToolResultBytes and how the agent recovers when a conversation outgrows the model's context window #720

Merged

Ethan-Arrowood approved these changes Oct 13, 2026

View reviewed changes

Ethan-Arrowood merged commit 3b0352f into main Oct 13, 2026
13 of 14 checks passed

Ethan-Arrowood deleted the docs/deploy-setup-github-actions branch October 13, 2026 20:41

dawsontoth mentioned this pull request Oct 14, 2026

Deployment tracking, replicated payload delivery, and rollback HarperFast/harper#641

Open

Navigation Menu

Repository navigation

Document `harper deploy setup=true provider=github-actions`, and how a workflow uses a trust policy - #722

Document `harper deploy setup=true provider=github-actions`, and how a workflow uses a trust policy#722
Ethan-Arrowood merged 12 commits into
mainfrom
docs/deploy-setup-github-actions

dawsontoth commented Oct 9, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

github-actions Bot commented Oct 12, 2026

Uh oh!

kriszyp left a comment

Uh oh!

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

This branch was previously deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dawsontoth commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⊙ Problem

❓ Your call: is a "Using it in a workflow" section the right fix?

💡 Solution

⚖️ Alternatives

❓ Your call: should every deploy role list registration_info?

🔧 Changes

✅ Verification

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 9, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 9, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 12, 2026

🚀 Preview Deployment

Uh oh!

kriszyp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Oct 13, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 13, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 13, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 13, 2026

🚀 Preview Deployment

Uh oh!

Uh oh!

github-actions Bot commented Oct 13, 2026

🧹 Preview Cleanup

Uh oh!

This branch was previously deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dawsontoth commented Oct 9, 2026 •

edited

Loading

❓ Your call: should every deploy role list `registration_info`?