docs(deploy): by-reference deploys, sealed credentials, CI token auth (draft)

[dawsontoth]

Draft, and stacked on #599 — this PR targets claude/two-phase-deploy-docs, not main, so the diff shows only what's new. Merge #599 first and this will retarget to main on its own. Like #599 it tracks unmerged work, so hold merge until the CLI PRs land and confirm the version badges against the shipping release.

#599 documents the two-phase deploy and revert_component. This covers the rest of the deploy-by-reference workflow — how you point a cluster at a commit, how it authenticates to a private source, and how CI authenticates to the cluster.

Documents harper#1850 (by_ref), harper#1851 (deploy setup), and harper#1876 (CI token auth). add_ssh_key generate=true (harper-pro#594) is already covered by #599.

What this adds

reference/components/applications.md

• Deploying by Reference — harper deploy by_ref=true, plus ref= and credential=. Leads with why: omitting package uploads an anonymous snapshot with no record of which commit it came from, so it can't be reproduced or stepped back from.

  Two things I made sure to call out explicitly, because both are quiet correctness traps:

  • A reference pins to a resolved SHA, not the tag or branch name you typed. Peers resolve the package independently, so a tag that moves mid-deploy — or a branch that advances — could otherwise leave nodes in a cluster running different code.
  • By-reference means the cluster builds from source. An app whose build can't run on the node should stay on payload deploys. (This is not hypothetical: it's exactly why create-harper's Next.js templates still deploy by payload — see create-harper#118.)

• Provisioning a Deploy Credential — harper deploy setup=true: the client-side sealing flow, that the plaintext never reaches the operations API, that it needs custody (Pro/Fabric), and that reverting to the previous version needs no credential at all (it reuses the retained build rather than re-fetching).

reference/cli/authentication.md

• Adds HARPER_CLI_REFRESH_TOKEN / HARPER_CLI_OPERATION_TOKEN to the supported variables, and a Token credentials for CI/CD section — so the CI recommendation is no longer "put an admin password in your pipeline". Covers precedence, the in-memory-only refresh, and token lifetimes (1d / 30d defaults).

• ⚠️ Documents a sharp edge I hit while verifying this: a user holds only one valid refresh token at a time. create_authentication_tokens overwrites a single hashed refresh_token on the user record (security/tokenAuthentication.ts), so issuing a new one invalidates the last — meaning a routine local harper login silently breaks a pipeline authenticating as the same account. The docs now recommend giving CI its own user, which also scopes its permissions and makes revocation independent.

reference/cli/commands.md

• harper login --for-ci, including the stdout/stderr split that makes harper login --for-ci | gh secret set --env-file - work without ever displaying the token.

reference/security/secrets.md

• Points the existing Private-source deploy credentials section at the CLI flow that automates it.

Verification

• Every anchor link in the changed files resolves (16 checked, including the pre-existing ones and the three new anchors other pages point at).
• prettier --check clean on all four files.

Notes for review

• Version badges use v5.2.0 to match docs(deploy): two-phase deploy_component, revert_component, stage/activate CLI (draft) #599's placeholder — worth confirming both against the actual shipping release before merge.
• I did not touch reference_versioned_docs/version-v4/ (v5 feature), consistent with docs(deploy): two-phase deploy_component, revert_component, stage/activate CLI (draft) #599.
• The --for-ci flag replaced an earlier interactive prompt in harper#1876; if that design shifts again, commands.md and the CI/CD section are the two places to update.

Related — deploy-by-reference effort

• HarperFast/documentation#599 — two-phase deploy docs (this PR's base)
• HarperFast/harper#1849 — two-phase stage/activate + revert_component
• HarperFast/harper#1850 — harper deploy by_ref=true
• HarperFast/harper#1851 — harper deploy setup=true
• HarperFast/harper#1876 — CI token auth + harper login --for-ci
• HarperFast/harper-pro#594 — add_ssh_key generate=true
• HarperFast/create-harper#118 — scaffolds this whole flow

🤖 Generated with Claude Code

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

[gemini-code-assist]

Code Review

This pull request updates the Harper CLI documentation to introduce features added in v5.2.0, including token-based credentials for CI/CD pipelines via harper login --for-ci, deploying components by git reference, and provisioning deploy credentials securely using client-side encryption. The review feedback correctly points out that the GitHub CLI (gh) does not support the --env-file flag used in the documentation examples, and provides a shell loop alternative to set multiple secrets from the command output.

[gemini-code-assist]

The gh secret set command in the GitHub CLI does not support a --env-file flag. To set multiple secrets from an environment file, you typically need to loop over the file's contents in your shell script or use a custom gh extension.

Consider providing a standard shell loop or pointing to the correct syntax for setting individual secrets.

Suggested change

	# Set both GitHub Actions secrets in one command — the token is never displayed
	harper login --for-ci | gh secret set --env-file -
	# Set GitHub Actions secrets by looping over the env-file output
	harper login --for-ci | while read -r line; do gh secret set "${line%%=*}" -b "${line#*=}"; done

[gemini-code-assist]

The gh secret set command in the GitHub CLI does not support a --env-file flag. To set multiple secrets from an environment file, you typically need to loop over the file's contents in your shell script or use a custom gh extension.

Consider providing a standard shell loop or pointing to the correct syntax for setting individual secrets.

Suggested change

	# Set both GitHub Actions secrets in one command
	harper login --for-ci | gh secret set --env-file -
	# Set GitHub Actions secrets by looping over the env-file output
	harper login --for-ci | while read -r line; do gh secret set "${line%%=*}" -b "${line#*=}"; done