Deployment Targets

Deployment Targets

PullPreview supports two deployment targets:

• compose: deploy your app with Docker Compose on the preview instance
• helm: bootstrap k3s on the preview instance and install a Helm chart

Set deployment_target in the workflow with: block to choose one. If you do not set it, PullPreview uses compose.

At a glance

Target	Best when	Main inputs	Runtime bootstrapped on the instance	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

compose

compose is the default target.

Use it when:

• your repo already has a Compose-based preview or dev setup
• you want the simplest preview runtime
• you need private registry login via registries
• you want to reuse multiple Compose files or custom docker compose up options

How it works:

• PullPreview provisions an instance and installs Docker Engine plus Docker Compose.
• It renders your Compose config 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.
• pre_script runs over SSH before docker compose up.
• If proxy_tls is set, PullPreview injects a Caddy sidecar that terminates TLS and forwards to the target Compose service.

Example:

- 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:8080
  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 already packaged and tested as a Helm chart
• you want preview deployments to exercise Kubernetes manifests and Helm templating
• you are okay with PullPreview bootstrapping k3s on each preview instance

How it works:

• PullPreview provisions an instance and installs k3s plus Helm.
• The chart is deployed as a single Helm release named app.
• The release runs in a dedicated namespace derived from the preview name.
• PullPreview deploys a Caddy Deployment that exposes one preview URL and routes to the Kubernetes Service named by proxy_tls.

Helm-specific rules:

• chart is required.
• proxy_tls is required.
• registries is not supported.
• Customized compose_files and compose_options are not supported.
• pre_script still runs before the Helm deployment.

Chart sources

chart can point to:

• a local chart path such as ./charts/my-app
• a repo chart name such as wordpress
• an OCI reference such as oci://registry.example.com/my-app

chart_repository is only used with repo chart names.

Placeholder expansion

For Helm previews, PullPreview expands these placeholders in proxy_tls and chart_set values:

• {{ pullpreview_url }}
• {{ pullpreview_public_dns }}
• {{ pullpreview_public_ip }}
• {{ release_name }}
• {{ namespace }}

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"
  env:
    HCLOUD_TOKEN: ${{ secrets.HCLOUD_TOKEN }}
    HETZNER_CA_KEY: ${{ secrets.HETZNER_CA_KEY }}

Which one should I choose?

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

Related pages:

• Getting Started
• Inputs
• Outputs
• Workflow Examples