Deployment targets — PullPreview docs

PullPreview supports two deployment targets: compose deploys your app with Docker Compose on the preview instance, while helm bootstraps a throwaway k3s cluster and installs a Helm chart. You select one with the deployment_target input under with:. The default is compose.

At a glance

Target	Best when	Main inputs	Runtime bootstrapped	HTTPS	Provider support
`compose`	Your app already runs with `docker compose up`	`compose_files`, `compose_options`, `registries`, `pre_script`, optional `proxy_tls`	Docker Engine + Docker Compose	optional	Lightsail, Hetzner
`helm`	Your app is already packaged as a Helm chart	`chart`, `chart_repository`, `chart_values`, `chart_set`, `proxy_tls`, optional `pre_script`	k3s + Helm	required	Lightsail, Hetzner

For the full list of inputs and their defaults, see the configuration reference.

compose (default)

Use compose when:

Your repository already runs with docker compose up.
You want the simplest possible runtime.
You need private registry login via registries.
You want to combine multiple Compose files or pass custom up options.

How it works:

PullPreview provisions the instance and installs Docker Engine and Docker Compose.
The Compose configuration is rendered on the GitHub runner. Relative bind mounts under app_path are rewritten to /app/..., and only the referenced local paths are synced to the instance.
Your pre_script runs over SSH before docker compose up.
If proxy_tls is set, PullPreview injects a Caddy sidecar that terminates TLS and forwards traffic to the target Compose service. The preview URL is then served over https on port 443.

- uses: pullpreview/action@v6
  with:
    deployment_target: compose
    compose_files: docker-compose.yml,docker-compose.pullpreview.yml
    compose_options: --build,--remove-orphans
    proxy_tls: web:80
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

helm

Use helm when:

Your app is packaged and tested as a Helm chart.
You want previews to exercise your Kubernetes manifests and templating.
You are comfortable with PullPreview bootstrapping k3s on each instance.

How it works:

PullPreview provisions the instance and installs k3s plus Helm.
The chart is deployed as a single Helm release named app in a dedicated namespace derived from the preview name.
PullPreview deploys a managed Caddy Deployment that exposes the main preview hostname plus any proxy_tls_hosts, routing them to the Kubernetes Service named by proxy_tls. Because TLS is always terminated this way, the preview URL is served over https on port 443.

Helm-specific rules

Input	Status under `helm`
`chart`	Required
`proxy_tls`	Required
`proxy_tls_hosts`	Optional — extra public hostnames reverse-proxied to the same `Service`
`registries`	Not supported
Customized `compose_files` / `compose_options`	Not supported
`pre_script`	Supported — runs before the Helm deployment

For more on proxy_tls and proxy_tls_hosts, see HTTPS and custom domains.

Chart sources

chart can point to any of the following:

Source	Example	`chart_repository`
Local chart path	`./charts/my-app`	Not used
Repo chart name	`wordpress`	Required
OCI reference	`oci://registry.example.com/my-app`	Not used

chart_repository is only used together with a repo chart name. Leave it unset for local paths and OCI references.

Placeholder expansion

For Helm previews, PullPreview expands the following placeholders in proxy_tls, chart_set, and the contents of chart_values files:

Placeholder	Expands to
`{{ pullpreview_url }}`	The preview URL
`{{ pullpreview_public_dns }}`	The instance public DNS name
`{{ pullpreview_public_ip }}`	The instance public IP
`{{ release_name }}`	The Helm release name (`app`)
`{{ namespace }}`	The dedicated namespace

chart_values files use plain string replacement, so a checked-in values file can contain {{ pullpreview_url }}, {{ pullpreview_public_dns }}, {{ release_name }}, {{ namespace }}, and the others directly. These placeholders are also documented alongside the other environment variables.

Example: repo chart

- uses: pullpreview/action@v6
  with:
    deployment_target: helm
    chart: wordpress
    chart_repository: https://charts.bitnami.com/bitnami
    chart_set: service.type=ClusterIP
    proxy_tls: "{{ release_name }}-wordpress:80"
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Example: local chart

- uses: pullpreview/action@v6
  with:
    app_path: .
    deployment_target: helm
    chart: ./charts/my-app
    chart_values: charts/my-app/values-preview.yaml
    chart_set: image.tag=${{ github.sha }},baseUrl={{ pullpreview_url }}
    proxy_tls: "{{ release_name }}-my-app:8080"
    proxy_tls_hosts: "admin.{{ pullpreview_public_dns }}"
  env:
    HCLOUD_TOKEN: ${{ secrets.HCLOUD_TOKEN }}
    HETZNER_CA_KEY: ${{ secrets.HETZNER_CA_KEY }}

Which one should you use?

Start with compose if your app runs outside Kubernetes and you want the least moving parts. Choose helm if your production packaging is Helm-based and you want previews to validate the chart itself.

If you are still setting things up, the getting started guide walks through your first preview end to end.