Configuration reference — PullPreview docs

The action is configured via the with: block in your workflow file. Below is the full input reference, grouped by purpose.

Provider credentials are passed as environment variables on the step (see Provider credentials).

Core inputs

Input	Default	Description
`app_path`	`.`	Path to the directory containing your `docker-compose.yml` (or Helm chart).
`label`	`pullpreview`	The GitHub label that triggers deployments. Change this if you want a different label name.
`admins`	`@collaborators/push`	Comma-separated list of GitHub logins (or the `@collaborators/push` magic value) whose SSH public keys are installed on the instance. Gives those users direct SSH access.
`deployment_target`	`compose`	Deployment engine: `compose` (Docker Compose) or `helm`.
`ttl`	`infinite`	Maximum lifetime of a preview environment. Only `h` (hours) and `d` (days) suffixes are recognized, e.g. `24h`, `7d`, or `infinite`. Any other value (e.g. `30m`) is treated as `infinite`. Expiry is measured from the PR’s last update and is enforced by the scheduled workflow run, so teardown can lag until the next scheduled run.
`default_port`	`80`	The port used when constructing the preview URL posted to the PR. Ignored when `proxy_tls` is set — the URL is then forced to HTTPS on port `443`.
`license`	(empty)	Your PullPreview commercial license key.

Networking

Input	Default	Description
`ports`	`80/tcp,443/tcp`	Comma-separated list of ports to open on the preview server (port 22 is always open). Format: `<port>/<protocol>`.
`cidrs`	`0.0.0.0/0`	IP range allowed to connect. Restrict this to your team’s IP range for private previews.
`dns`	`my.preview.run`	DNS suffix for the generated preview hostname. Use one of `rev1.click`–`rev9.click` or your own domain to avoid Let’s Encrypt rate limits on the shared default.
`max_domain_length`	`62`	Maximum length of the fully qualified domain name. Cannot exceed 62 due to Let’s Encrypt restrictions.

TLS and proxy

Input	Default	Description
`proxy_tls`	(empty)	Enable automatic HTTPS with Let’s Encrypt via Caddy. Format: `<service>:<port>`, where `port` is the internal port your service listens on (Caddy terminates TLS), e.g. `web:80`. Leave empty to skip TLS termination. Setting this forces the preview URL to `https://…:443`. See HTTPS and custom domains.
`proxy_tls_hosts`	(empty)	Helm only. Additional public hostnames served by the Helm Caddy gateway, comma-separated. They reverse-proxy to the same `proxy_tls` upstream. Supports placeholders like `{{ pullpreview_public_dns }}`.

Docker Compose inputs

These inputs apply when deployment_target is compose (the default). They are not supported for Helm previews (except for their untouched default values).

Input	Default	Description
`compose_files`	`docker-compose.yml`	Comma-separated list of Compose files passed to `docker compose -f`.
`compose_options`	`--build`	Additional options passed to `docker compose up`.
`registries`	(empty)	Private registries to authenticate against, comma-separated. Format: `docker://username:[email protected]`. A token-only form `docker://[email protected]` is supported (useful for GHCR). Invalid entries are skipped with a warning. See Private registries.
`pre_script`	(empty)	Path (relative to `app_path`) to a bash script executed over SSH on the instance before the deployment (`docker compose up`, or the Helm release for `helm`). See Pre-deploy script.

Helm inputs

These inputs apply when deployment_target is helm. Helm requires both chart and proxy_tls. See Deployment targets.

Input	Default	Description
`chart`	(empty)	Helm chart reference: a local path, a repo chart name, or an `oci://` reference. Required for Helm.
`chart_repository`	(empty)	Helm repository URL used when `chart` is a repo chart name. Do not set it for local paths or OCI references.
`chart_values`	(empty)	Comma-separated list of Helm values files (relative to `app_path`). File contents support placeholder expansion (e.g. `{{ pullpreview_url }}`, `{{ release_name }}`).
`chart_set`	(empty)	Comma-separated `--set` overrides passed to Helm. Supports the same placeholders.

Provider and instance

Input	Default	Description
`provider`	`lightsail`	Cloud provider: `lightsail` (AWS) or `hetzner`.
`instance_type`	`small`	Provider-specific instance size. Lightsail uses bundle names: `nano`, `micro`, `small`, `medium`, `large`, `xlarge`, `2xlarge` (default `small` → the Lightsail “small” bundle). Hetzner uses real server types like `cpx11`, `cpx21`, `cpx22` — the Lightsail aliases do not apply; the default `small` (and `micro`/empty) resolves to `cpx22`, and any other value is passed to Hetzner verbatim. See Providers.
`region`	(empty)	Cloud region or Hetzner location. Overrides the provider default (`us-east-1` for Lightsail, `nbg1` for Hetzner). Passed through to the provider — not validated against an allowlist.
`image`	`ubuntu-24.04`	Instance base image. Applies to Hetzner only; Lightsail ignores it and always uses Amazon Linux 2023.
`deployment_variant`	(empty)	Up to 4 characters. Allows multiple independent preview environments from the same PR (e.g. `fe` and `be`). See Multiple environments per PR.

URL customization

Input	Default	Description
`templated_url`	(empty)	Template for the preview URL shown in PR comments and the `url` output. Use `{{ pullpreview_url }}` as a placeholder, e.g. `{{ pullpreview_url }}/app/login`.

Other

Input	Default	Description
`github_token`	`${{ github.token }}`	Token used for GitHub API operations (labels, comments, collaborator/key lookup). The default usually suffices; override only if you need elevated scopes.
`force_action`	(empty)	Override the event-derived action with `up` or `down`, while keeping normal PR comments, summary output, and cleanup scope. Useful for manual `workflow_dispatch` deploys or teardowns.

Provider credentials

Pass credentials as environment variables on the pullpreview/action step.

AWS Lightsail

env:
  AWS_ACCESS_KEY_ID: "${{ secrets.AWS_ACCESS_KEY_ID }}"
  AWS_SECRET_ACCESS_KEY: "${{ secrets.AWS_SECRET_ACCESS_KEY }}"
  AWS_REGION: "us-east-1"

PullPreview only uses the Lightsail API. For production, prefer short-lived credentials via GitHub OIDC and a least-privilege (lightsail:*) IAM policy — see Recommended AWS setup.

Hetzner Cloud

env:
  HCLOUD_TOKEN: "${{ secrets.HCLOUD_TOKEN }}"
  HETZNER_CA_KEY: "${{ secrets.HETZNER_CA_KEY }}"

HETZNER_CA_KEY is a PEM-encoded SSH CA private key that PullPreview uses to sign short-lived SSH access certificates (it is not a TLS key). It is always required for Hetzner. Generate it once and store it as a secret; PullPreview reuses it across deploys:

ssh-keygen -t rsa -b 3072 -m PEM -N "" -f hetzner_ca_key

Action outputs

The action sets these step outputs (access via steps.<step-id>.outputs.<name>):

Output	Description
`live`	`true` if this run produced a live preview deployment, `false` otherwise (destroy, cleanup, and no-op runs are `false`).
`url`	The full preview URL, including scheme and explicit port — `http://…:80` by default, `https://…:443` when `proxy_tls` is enabled. Empty for non-live runs.
`host`	The preview instance’s public IP address (always the IP, even when `url` uses a DNS hostname).
`username`	The SSH username for the preview server — `ec2-user` on Lightsail, `root` on Hetzner.

- id: pullpreview
  uses: pullpreview/action@v6
  # ...

- name: Print preview URL
  if: steps.pullpreview.outputs.live == 'true'
  run: echo "Preview URL: ${{ steps.pullpreview.outputs.url }}"