feat: deploy on merge to main with GitHub OIDC instead of a stored refresh token

[dawsontoth]

⊙ Problem

create-harper projects deploy on version tags with a refresh token stored as a GitHub secret, which someone has to mint and paste in, and which expires. Closes #144. Closes #145. Part of #143.

❓ Your call: should this wait for Harper 5.4.0?

deploy:setup-ci runs core Harper's new setup command (HarperFast/harper#3127), at the maintainer's direction, instead of #145's script in every template. On an earlier Harper it fails with an unknown provider, so this shouldn't merge before 5.4.0 ships. The alternative was shipping manual setup steps now.

💡 Solution

• Every template's workflow tests pull requests and deploys when a change merges to main. The deploy job stores no credential: its harper commands authenticate with GitHub's OIDC token.
• npm run deploy:setup-ci sets the cluster up once.
• The deploy waits for every node to take the release, and the run summary names the deployment and its certification.
• The deploy user can deploy any app on the cluster (Scope deploy permissions to component names harper#3046), so the README says to protect main.

⚖️ Alternatives

• Deploy by reference (by_ref=true) — needs a clone credential on the cluster and can't carry a build's output, which the Next.js templates need.
• Keep the refresh-token secret and only change the trigger — keeps a stored, expiring credential, and a user has one refresh token, so CI would need its own user.

❓ Your call: is a re-run guard enough to keep an older commit from deploying last?

Runs on main go one at a time, and a re-run refuses a commit that is no longer the tip. GitHub doesn't promise push order within the group, so two pushes arriving out of order could still deploy the older one last. A stricter guard brought back a case where nothing deploys.

❓ Your call: is a wait that can miss the job acceptable for now?

The rolling job lives only on the node that received the deploy. If the wait's polls never reach that node through a load balancer, the step fails with the outcome unknown, never a false success. HarperFast/harper#3060 fixes this by recording each node's outcome on the replicated deployment record.

🔧 Changes

• The shared workflow runs tests on pull_request, and deploys on push to main and workflow_dispatch. The deploy job:

  • is the only job with id-token: write;
  • has the re-run guard and persist-credentials: false;
  • runs the payload deploy, then the rolling-job wait (verified against Harper in Deploying from CI: lead with OIDC, and correct the deploy reference where it disagrees with Harper documentation#713), then a run summary.

  Concurrency orders runs per ref. actions/checkout and actions/setup-node move to this repository's v7 pins. The Next.js copies add a build step.

• Every template gets the workflow (fanned out by applySharedTemplates), package scripts where deploy is the payload deploy, deploy:setup-ci is new and deploy:setup is gone, and a README ## Deployment section. That section covers how the workflow's harper commands authenticate, one-time setup, certification, going back by deployment_id, staging, a refused run, migrating an older project, and private npm registries:

  • nextjs: workflow, package.json, README
  • nextjs-ts: workflow, package.json, README
  • react: workflow, package.json, README
  • react-ts: workflow, package.json, README
  • react-ssr: workflow, package.json, README
  • react-ts-ssr: workflow, package.json, README
  • vanilla: workflow, package.json, README
  • vanilla-ts: workflow, package.json, README
  • vue: workflow, package.json, README
  • vue-ts: workflow, package.json, README
  • vue-ssr: workflow, package.json, README
  • vue-ts-ssr: workflow, package.json, README

• The root README, --help and the closing message point at the same steps.

• lib/pkg/toComponentName.js and the your-component-name-here placeholder.

• The Studio template build now drops the whole Deployment section, and applySharedTemplates' note explains why the Next.js copies stay separate.

• The vanilla templates list @harperfast/schema-codegen in dependencies (vanilla-ts), since config.yaml loads it and the cluster's install skips devDependencies.

• At the maintainer's direction, copyFile comments out a placeholder target in a scaffolded .env, which the CLI would otherwise use ahead of the harper login target. harper login in the project then adds the real one.

• The setup command is documented in Document harper deploy setup=true provider=github-actions, and how a workflow uses a trust policy documentation#722.

✅ Verification

• npm test: 366 tests, including the workflow tests. npm run lint:check, npm run format:check and commitlint pass.
• End to end against a local build of Set up GitHub Actions deploys with harper deploy setup=true provider=github-actions harper#3127, with a mock OIDC issuer: a vanilla project scaffolded with no URL, harper login, npm run deploy:setup-ci, then the workflow's own deploy steps. The release was certified, the wait saw COMPLETE, and the app served.
• Not run: a real GitHub Actions deploy, which needs Harper 5.4.0 (Deploy on merge to main with GitHub OIDC instead of a stored refresh token #144's done-when).

What the tests and the end-to-end run cover

• template.tests/deployWorkflow.test.js: the trigger, id-token: write on the deploy job only, no stored credential, persist-credentials: false, the explicit project, the wait loop, concurrency, the re-run guard and the pins, a hostile directory name, numeric ones, and every package config.yaml loads being a dependency.
• template.tests/template.test.js, now in the default suite, checks the commented-out target and a scaffold with a URL; copyFile's tests cover each placeholder form. The closing-message test covers the deploy note.
• End to end: harper login wrote the real target into .env; setup ran through a fake gh; the deploy job ran with no stored credential and the cluster logged no refused operation. A token from another branch or environment, or after drop_oidc_trust, was refused. The first run found the devDependency and placeholder-target bugs fixed here.

🤖 Generated with Claude Code

Related PRs: #146 overlaps (it set HARPER_CLI_TARGET in the scaffolded .env; this comments out the placeholder it writes when no URL is given)
Complexity: medium

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

_{Review-Attention: study ~13m (decisions: payload-over-by-reference, guard-on-rerun-only, cluster-wide-deploy-user, app-prefix-for-json-literals, comment-out-placeholder, dotenv-runtime-dependency, do-less-alternative) @ cfa5b75}

[gemini-code-assist]

Code Review

This pull request migrates the template deployment workflows to a modern, OIDC-based GitHub Actions deployment model, eliminating the need for stored Harper credentials in GitHub. It introduces a new deploy:setup-ci script across templates, sanitizes project directory names into valid Harper component names, and updates the scaffolding process to guide users through the new deployment setup. Feedback is provided regarding a fragile regular expression used to strip the deployment section in Studio templates, which could fail if it is the last section in the README.

[kriszyp]

_{🤖 Reviewed with Codex}

[kriszyp]

major — polling can miss the node-local rollout job.

[dawsontoth]

Known limitation, kept on purpose: CI uses the single cluster URL, and per-node URLs would need a trust policy for each node. The job record only exists on the node that received the deploy. If the polls never reach that node, the step fails, reporting that the job's outcome is unknown, and never reports success it can't see. The fix belongs in core: HarperFast/harper#3060 records each node's outcome on the replicated deployment record, and the workflow will switch to polling get_deployment when it lands. Polling through the CLI (HarperFast/harper#3058) would hit the same problem unless it streams the deploy or reads that record.

🤖 Posted by Claude Code