PR previews: Previews panel for an application #2044

Part of HarperFast/harper#3042 (PR preview deployments). This replaces HarperFast/central-manager#906: the customer's cluster owns previews, so Studio talks to the cluster directly and Central Manager has no part in it.

Problem

Harper 5.4 can run a preview for each PR of an application, but turning that on takes the CLI: harper preview setup, run from a checkout of the repository. Studio can't enable previews, show what's running, or remove them.

Proposal

Add a Previews panel to an application, for super users on 5.4+. Studio calls the cluster over its operations URL as the signed-in super user, as #1788 does for deploys.

1. Enable. A toggle, with these inputs:

   • the GitHub repository;
   • the branch (main by default);
   • the data mode: branched (the default) or shared;
   • the limits: maxPreviews, and maxTtlDays (7 by default).

   It calls enable_previews with app, repository, repository_id, branch, audience and those options. audience is the cluster's operations URL, exactly as the CLI requests it, and hostSuffix is needed only when that isn't a host name. Enable is create-only and creates the role, the user and two trust policies. It answers 409 and writes nothing when a record differs or another enabled policy would match the same runs, so show that message as it comes.

2. Status. Read get_preview_policy and show enabled, the repository, the limits from grant, and each entry in problems.

3. Live previews. List the get_components entries that carry preview, filtered to this application: PR, branch, commit, URL (from host) and expiry.

4. Delete a preview. Call drop_component for that entry, and show its per-node results.

5. Disable. Call disable_previews, after a confirmation that says it revokes the CI identity and drops every preview of the application. If it stops partway, with a failed drop or an unreachable node, the identity stays revoked: show why and offer a rerun, which resumes.

6. What to commit. Show the workflow file and the HARPER_PREVIEW_TARGET value to set as a repository variable, plus the two environments the workflow uses, preview and preview-cleanup. Today that file is the starter harper preview setup writes (starterPreviewWorkflow in bin/previewSetup.ts). Show the HarperFast/deploy-action form instead once A reusable GitHub Action for Harper deploys, with a PR preview mode harper#3055 ships.

7. Warnings.

   • In shared mode, a preview's writes reach the cluster's databases.
   • Previews are the same site as what production serves from the cluster's host name. See the security model in [Epic] PR preview deployments harper#3042.

Also add enable_previews, disable_previews and get_preview_policy to the operations catalog as super-user only, since their handlers enforce that too.

To decide

• Private repositories also need a sealed deploy credential (harper preview setup credential=true, Grant a deploy credential to a component-name pattern harper#3090). Either the panel does this, or it sends the user to the CLI for that step.
• Repository id: share the lookup with Set up deploys from GitHub Actions: trust policy, deploy role and workflow #1788 rather than building a second one.

Related

• Enable PR previews from the cluster: enable_previews and disable_previews, per-app preview limits, and harper preview setup harper#3617 added the operations. The names come from derivePreviewNames in utility/previewIdentity.ts, and security/DESIGN.md describes the design.
• Set up deploys from GitHub Actions: trust policy, deploy role and workflow #1788 is the same trust setup for production deploys.

Done when

A user with a 5.4 cluster turns previews on in the panel, commits the workflow it shows and sets the variable. Their next PR appears in the panel with a working URL, and closing the PR removes it. Deleting a preview works from the panel, disabling removes every preview and the identity, and the panel shows any problem get_preview_policy reports.