A reusable GitHub Action for Harper deploys, with a PR preview mode #3055

Problem

There's no reusable deploy action. Every repository calls the CLI inline, and no workflow uses the OIDC deploys added in 5.3.0.

The documentation site's preview workflow (HarperFast/documentation#695) shows the cost:

• It is about 250 lines.
• It stores a username and password.
• It serves previews under a path.
• It has no expiry.

Proposal

A HarperFast/deploy-action, built on harper deploy and harper preview. It could live in a new repository or be published from this one.

• Normal deploys, authenticated by OIDC.
• preview: true:
  • On opened, synchronize and reopened: deploy, then post one PR comment (updated in place) and a GitHub Deployment with environment_url.
  • On closed: drop the preview and mark the deployment inactive.
  • On schedule: drop previews whose PR is closed.
• Docs: a guide, and this workflow in the create-harper templates.

on:
  pull_request:
    types: [opened, synchronize, reopened, closed]
  schedule:
    - cron: '17 3 * * *'
jobs:
  preview:
    runs-on: ubuntu-latest
    environment: harper-preview
    permissions: { id-token: write, contents: read, pull-requests: write, deployments: write }
    steps:
      - uses: actions/checkout@v7
        if: github.event.action != 'closed'
      - run: npm ci && npm run build
        if: github.event.action != 'closed'
      - uses: HarperFast/deploy-action@v1
        with:
          cluster: ${{ vars.HARPER_PREVIEW_CLUSTER }}
          app: shop
          path: dist
          preview: true

Part of #3042.

Update, 2026-10-07: use the trust pattern from HarperFast/documentation#715

The example above (pull_request plus an environment) is superseded by the pattern HarperFast/documentation#715 verified on 5.3.0:

• Trigger: pull_request_target, with the workflow running from the default branch and no PR checkout on the runner. A same-repository condition skips fork PRs.
• Trust policy: pins workflow_ref to the default branch's workflow file, event_name: pull_request_target, and an environment.
• Deploy:
  • Source apps deploy by_ref at the PR's head SHA.
  • Apps that need a build publish each PR commit from a separate, unprivileged workflow, then deploy the package (or a payload, once Payload deploys can set host, urlPath, isolated and branchedDatabases #3043 lands).
• Public repositories: GitHub's default execution protection blocks pull_request_target for affected public repositories from 2026-11-02. The action's docs must say how to allow it.
• Approvals: required reviewers also gate cleanup runs. Consider a separate drop-only cleanup path, so closures don't wait on approval.