Getting Started

1. Add a Docker Compose app

PullPreview deploys any app that can be started by Docker Compose.

By default it looks for docker-compose.yml in your repository root.

If your compose file is elsewhere, set app_path and/or compose_files in workflow inputs.

2. Create the pullpreview label

Create a repository label named pullpreview (or use another label and set label input).

3. Configure cloud credentials

By default, PullPreview provisions Lightsail instances in your AWS account. You can also use Hetzner by setting provider: hetzner.

Lightsail (default)

Add repository secrets:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• optional AWS_REGION (defaults to us-east-1)

For least privilege setup, see Recommended AWS Configuration.

Hetzner

Add repository secret:

• HCLOUD_TOKEN
• HETZNER_CA_KEY

HETZNER_CA_KEY is a private SSH key used by PullPreview as an SSH CA for per-run cert authentication. Generate one once and store it as a secret:

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

Keep only the private key in the secret (do not upload the .pub file).

And set action inputs:

• provider: hetzner
• optional region (defaults to nbg1)
• optional image (defaults to ubuntu-24.04)
• optional instance_type (defaults to cpx21)

4. Add workflow file

Create .github/workflows/pullpreview.yml:

name: PullPreview
on:
  schedule:
    - cron: "30 */4 * * *"
  push:
    branches: [master]
  pull_request:
    types: [labeled, unlabeled, synchronize, closed, reopened, opened]

concurrency: ${{ github.ref }}

permissions:
  contents: read
  pull-requests: write

jobs:
  deploy:
    if: github.event_name == 'push' || (github.event.action != 'closed' && github.event.action != 'unlabeled' && (github.event.label.name == 'pullpreview' || contains(github.event.pull_request.labels.*.name, 'pullpreview')))
    runs-on: ubuntu-slim
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v5
      - uses: pullpreview/action@v6
        with:
          admins: "@collaborators/push"
          always_on: master
          app_path: .
          # optional: switch provider
          # provider: hetzner
          # region: nbg1
          # image: ubuntu-24.04
          # instance_type: cpx21
          # optional: automatic HTTPS termination with Let's Encrypt
          # proxy_tls: web:80
        env:
          # Lightsail credentials (default provider)
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: us-east-1
          # Hetzner credential (only when provider: hetzner)
          # HCLOUD_TOKEN: ${{ secrets.HCLOUD_TOKEN }}
          # HETZNER_CA_KEY: ${{ secrets.HETZNER_CA_KEY }}

5. Deploy

Open a PR, add the pullpreview label, and watch the workflow run.

You will get:

• workflow checks
• PR comment updates (building/ready/error/destroyed)
• GitHub job summary with preview + logs links
• SSH connection details in logs and summary when deploy succeeds

For more patterns, see Workflow Examples and Lifecycle.