PullPreview
GitHub Get started

FAQ

Common questions about PullPreview answered concisely.

Which cloud providers are supported?

AWS Lightsail and Hetzner Cloud. Set provider: lightsail (default) or provider: hetzner in your workflow. There are no plans to add other providers at this time, but Lightsail is available in most AWS regions and Hetzner has locations across Europe and the US. See Providers for a full comparison.

Does my source code leave GitHub?

No. PullPreview runs as a GitHub Action inside your own GitHub Actions runner. actions/checkout checks out your code on the runner, and the action then syncs it over SSH to the preview server (which is in your own cloud account). Your code never passes through any PullPreview-operated infrastructure. The action is open source, so you can audit it. Also note that GitHub Actions does not expose secrets to workflows triggered by pull requests from forks, so external contributors can’t read your cloud credentials.

What does it cost?

Two separate costs:

  1. PullPreview license. 300 €/year per GitHub organization. Non-profit and individual use can be free — contact [email protected] or purchase a license ↗.
  2. Cloud compute. You pay your provider (AWS or Hetzner) directly for the time each preview instance runs. There is no per-preview markup. The action’s default instance_type is small (the Lightsail “small” bundle, or cpx22 on Hetzner). If you want the cheapest possible box, set instance_type explicitly — a Lightsail nano or a Hetzner cpx11 runs a few euros/dollars a month. With a short ttl and typical PR churn, monthly costs are usually small.

Do I need Docker Compose?

For the default compose deployment target, yes — your app must be launchable with docker compose up. If you already have a Helm chart, you can set deployment_target: helm and point chart at your chart. See Deployment targets for the full Helm guide.

Can reviewers SSH into the preview server?

Yes. The admins input accepts a comma-separated list of GitHub usernames whose public SSH keys are fetched from GitHub and installed on the instance. You can also use the @collaborators/push magic value to automatically include all repository collaborators with push access (up to the first 100). The SSH username is available in the username step output (ec2-user on Lightsail, root on Hetzner), and the job summary prints the full SSH command. See Troubleshooting.

How does cleanup work?

Three mechanisms (all require the if: guard to let those events run the job):

  1. Label removal. Removing the pullpreview label from a PR destroys the instance (the pull_request: unlabeled event triggers the workflow).
  2. PR close/merge. Closing or merging the PR triggers the workflow’s closed event and destroys the instance.
  3. TTL. If you set ttl: 24h (only h/d suffixes are recognized; anything else means never expire), the scheduled workflow run checks whether any preview has exceeded its TTL — measured from the PR’s last update — and destroys it. Because it only runs on the schedule, teardown can lag until the next scheduled run. This is a safety net for forgotten environments.

State (Docker volumes) persists across redeploys on the same PR, but is not preserved after destruction. Opening a new PR or re-labeling starts fresh. See Seeding data to populate a preview database.

Why is my deploy blocked, and what is sent to PullPreview’s servers?

On each deploy/destroy, the action makes one request to app.pullpreview.com/licenses/check with your org and repo IDs to validate the license. If the license server returns a negative result, the run is stopped with the returned message. If the license server is unreachable, the check fails open and the deploy continues. No source code or credentials are sent — only the org/repo identifiers.

How do I get a license?

Purchase at buy.pullpreview.com ↗. After purchase you will receive a license key. Set it as the license input in your workflow:

with:
  license: "${{ secrets.PULLPREVIEW_LICENSE }}"

Add the key as a GitHub Actions secret named PULLPREVIEW_LICENSE. Non-profit teams and solo developers can request a free license by emailing [email protected].

Can I run multiple preview environments from the same PR?

Yes. Use the deployment_variant input (up to 4 characters) to create independent environments from a single PR. For example, deploy a frontend and a backend variant in parallel:

- uses: pullpreview/action@v6
  with:
    deployment_variant: "fe"
    compose_files: docker-compose.frontend.yml

Each variant gets its own hostname and instance. See Multiple environments per PR for the full two-job workflow.

Where can I find more detailed documentation?

Browse the rest of these docs: