Set up GitHub Actions deploys with harper deploy setup=true provider=github-actions

[dawsontoth]

⊙ Problem

A GitHub Actions workflow can deploy with its OIDC identity token instead of a stored credential, but the cluster needs a deploy role, a user, and a trust policy whose claims match the workflow exactly. Writing those by hand is error-prone, and a mismatch shows up only as a 401 in CI.

❓ Your call: does this belong in core?

It is a provider on harper deploy setup=true, at the maintainer's direction, instead of HarperFast/create-harper#145's script in every template. A "no" moves it back into create-harper as a script; the provider is additive, so removing it is easy.

💡 Solution

harper deploy setup=true provider=github-actions project=my-app, run once from the repository's checkout:

• creates a role and user that can only deploy, wait for the rollout and check the version;
• creates a trust policy pinned to the repository, the workflow on main, and the production environment;
• checks that policy against the workflow file first, and refuses a workflow that could never use it;
• sets the repository's HARPER_CLI_TARGET variable if it has none.

It only creates. A rerun changes nothing, and a record or variable that already differs stops it before it writes.

⚖️ Alternatives

• A setup script in each create-harper template — a fix would mean regenerating every project, and Studio templates would carry an orphan file.
• A server operation that creates role, user and policy together — the GitHub half is client-side anyway, and the cluster half is three existing operations.
• Reconcile existing records to the desired state — could repurpose a role another app uses.

❓ Your call: is the policy-write race acceptable?

Setup never writes an existing policy, so it can't undo a disable or a drop. A policy with the same id that another super user creates in the one round trip before the write would be replaced. A no-replace flag on add_oidc_trust would narrow that, not close it, since hdb_oidc_trust replicates.

❓ Your call: should a failed repository lookup refuse?

workflow_ref is compared exactly, so setup looks the repository up for GitHub's spelling. When that fails (a private repo without gh), it proceeds with the name as typed and says so. Refusing would block that case entirely.

🔧 Changes

• bin/deploySetup.ts asks for the provider first and routes github-actions before the secrets-custody fetch it doesn't need. Component resolution is shared.
• bin/deploySetupGithubActions.ts is the new provider:
  • names <project>-ci-deploy and github-actions-<project>, which Studio's setup (Set up deploys from GitHub Actions: trust policy, deploy role and workflow studio#1788) must match; the role's operations are deploy_component, get_job and registration_info, and setup says the role can deploy any component (Scope deploy permissions to component names #3046);
  • one canonical workflow path for the file check and the claim;
  • the workflow check, parsed with YAML's failsafe schema so 1.0 stays a branch name. It refuses a workflow with no job environment and one where no job in the environment grants id-token: write, and runs only in the target repository's own checkout;
  • the create-only plan, where a role with structure_user or cluster_user is a conflict, and the claim-by-claim readback;
  • the target is pinned only when it came from a saved login, so credentials in an explicit target survive;
  • the variable: read first, created with a POST that never replaces, kept or left by what it names, and exit 1 with the gh command when it isn't set.
• bin/cliOperations.ts also keeps each argument as typed on a non-enumerable _rawArgs, read by rawStringArg, since buildRequest JSON-parses branch=1.0 into 1. It exports resolveGitRepo.
• security/DESIGN.md records the create-only rule, the names Studio must match, and the race.

✅ Verification

• Unit tests: reconcile decisions, workflow checks and raw arguments, with the deploySetup and cliOperations suites: 153 passing.
• End to end against a local build with a mock OIDC issuer: a create-harper project's deploy:setup-ci, then its workflow's own deploy steps with no stored credential. The exchange authenticated, the release was certified, and get_job returned COMPLETE.
• The integration test drives the CLI against a real Harper (fixture, schema). It needs the loopback alias pool, so it runs in CI only.
• Not run: a token from GitHub's own issuer, or a rollout across several nodes.

Every case run live, and the local gate results

• Setup: the lookup corrected acme/my-app to GitHub's Acme/My-App; the scaffolded deploy.yaml passed the check; a rerun changed nothing; no gh exits 1 with the command; a widened role and an inactive user are refused and left as they were; a workflow on another branch, or without id-token: write, is refused before any write; branch=1.0 is pinned as typed; credentials in the target URL authenticate every call; a differently spelled workflow path pins the canonical one.
• Variable: absent is created with one POST; one naming this cluster without the trailing slash is kept; one naming another cluster, including one created between the read and the POST, is left with exit 1 and its user:password@ removed.
• A checkout of acme/my-app with repo=acme/other skips the workflow check with a note.
• The exchange: the policy copied under the mock issuer (only issuer changed, plus the sub the generic profile requires). The same token was refused describe_all. A token from another branch or environment, or after drop_oidc_trust, was refused, and the deploy failed.
• Integration cases: the stored records, a conflicting role refused and left alone, credentials in the target URL.
• macOS gates: npm run lint and test:unit:resources (4071) pass. test:unit:main hangs at components/applicationSpawn.test.js and fails six files, exactly as a clean origin/main build does here; CI's Ubuntu run is the gate for them.

🤖 Generated with Claude Code

Release target: v5.4 — new CLI surface, not a backport; HarperFast/create-harper#147 needs it in 5.4.0
Related PRs: none found (partial scan: 3 PRs merged since 2026-10-08 beyond the first 50 were not scanned)
Complexity: medium

_{Review-Coverage: authored=claude; ran=gemini,cursor-muse,codex,cursor-composer; adjudicated=domain; blocked=cursor-grok(failed),claude(fallback)(out-of-budget); declined=cursor-kimi; rounds=8; full=3 @ abe0935}

_{Review-Attention: read ~8m (decisions: do-less-alternative, variable-create-only, workflow-check-hard-refusal, checkout-identity-gate, client-composition-vs-server-create-only, exact-operation-set-match, cluster-wide-deploy-role) @ abe0935}

[gemini-code-assist]

Code Review

This pull request introduces support for GitHub Actions OIDC trusted publishing via the harper deploy setup=true provider=github-actions command. It adds a new module to check workflow files, reconcile roles, users, and trust policies, and configure repository variables. It also preserves raw CLI arguments to prevent numeric-looking branch names from being parsed as numbers. Feedback highlights that the fallback GitHub API fetch request in bin/deploySetupGithubActions.ts lacks a required User-Agent header, which will cause the API to reject the request with a 403 error when the gh CLI is unavailable.

[kriszyp]

_{🤖 Reviewed with Codex}

[kriszyp]

major — A concurrent policy change can be overwritten, undoing a revocation.

[dawsontoth]

Setup can't undo a revocation. It writes a policy only when none exists, at the preflight and again just before the write; an existing policy that differs or is disabled stops setup before it writes anything. Deactivating the user also holds, because setup refuses an inactive user and add_oidc_trust rejects a policy that names one. The remaining window is a policy with the same id created by someone else in the one round trip before the write, which setup would replace. add_oidc_trust could take a no-replace flag (Table.create 409s), but hdb_oidc_trust replicates, so that check is per node and narrows the window rather than closing it. A 5.3 cluster would also ignore the flag. I've left it as documented in security/DESIGN.md, and corrected "creates or disables" to "creates" there and in the docs (abe0935, HarperFast/documentation#722).

🤖 Posted by Claude Code