PullPreview

https://pullpreview.com/docs
Admin
PullPreview is a GitHub Action that automatically deploys pull requests as live preview environments...
Tokens:9,694
Snippets:141
Trust Score:6.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Guard one-time setup with PULLPREVIEW_FIRST_RUN

Source: https://pullpreview.com/docs/environment-variables

Use the PULLPREVIEW_FIRST_RUN variable in shell scripts to execute setup tasks like database seeding only during the initial deployment.

```bash
if [ "$PULLPREVIEW_FIRST_RUN" = "true" ]; then
  ./bin/seed
fi
```

--------------------------------

### Build and Run CLI from Source

Source: https://pullpreview.com/docs/cli

Commands to verify the CLI installation or build the binary from the repository source.

```bash
mise exec -- go run ./cmd/pullpreview --help
mise exec -- go build -o pullpreview ./cmd/pullpreview
```

--------------------------------

### Configure Hetzner Provider

Source: https://pullpreview.com/docs/cli

Environment variable setup for targeting Hetzner infrastructure.

```bash
PULLPREVIEW_PROVIDER=hetzner \
HETZNER_CA_KEY="$(cat ~/.ssh/hetzner_ca_key)" \
HCLOUD_TOKEN=... \
pullpreview up ./path/to/app \
  --deployment-target helm \
  --chart ./charts/my-app \
  --proxy-tls '{{release_name}}-web:80' \
  --region nbg1 \
  --image ubuntu-24.04 \
  --instance-type cpx22
```

--------------------------------

### Configure PullPreview Action and Access Outputs

Source: https://pullpreview.com/docs/configuration

Basic setup for the PullPreview action and a conditional step to print the generated preview URL.

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


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

--------------------------------

### Configure Docker Compose deployment

Source: https://pullpreview.com/docs/deployment-targets

Example configuration for deploying with Docker Compose, including multiple files and TLS proxy settings.

```yaml
- 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 }}
```

--------------------------------

### Configure multiple registries

Source: https://pullpreview.com/docs/private-registries

Example of combining multiple registry credentials in a single comma-separated string.

```yaml
- uses: pullpreview/action@v6
  with:
    deployment_target: compose
    registries: docker://${{ secrets.GHCR_PAT }}@ghcr.io,docker://${{ secrets.DOCKERHUB_USER }}:${{ secrets.DOCKERHUB_PASSWORD }}@index.docker.io
```

--------------------------------

### Configure GHCR authentication

Source: https://pullpreview.com/docs/private-registries

Example of using a token-based credential for GitHub Container Registry.

```yaml
- uses: pullpreview/action@v6
  with:
    deployment_target: compose
    registries: docker://${{ secrets.GHCR_PAT }}@ghcr.io
```

--------------------------------

### Configure registries in GitHub Actions

Source: https://pullpreview.com/docs/private-registries

Example of providing multiple registry credentials within the pullpreview/action workflow step.

```yaml
- uses: pullpreview/action@v6
  with:
    deployment_target: compose
    registries: docker://${{ secrets.DOCKERHUB_USER }}:${{ secrets.DOCKERHUB_PASSWORD }}@index.docker.io,docker://${{ secrets.GHCR_PAT }}@ghcr.io
```

--------------------------------

### Inspect Instance State via SSH

Source: https://pullpreview.com/docs/troubleshooting

Use these commands to connect to the instance and inspect container status and logs when a deployment fails.

```bash
ssh ec2-user@<ip>   # use root@<ip> on Hetzner
docker ps -a
docker logs <container>
```

--------------------------------

### Basic CLI Operations

Source: https://pullpreview.com/docs/cli

Standard commands for deploying, listing, and destroying infrastructure instances.

```bash
# Deploy a local project
pullpreview up ./path/to/app --name pullpreview-local --instance-type small --region us-east-1
# List deployments created by PullPreview
pullpreview list
pullpreview list my-org/my-repo
# Destroy a deployment by instance name
pullpreview down --name pullpreview-local
```

--------------------------------

### Deploy with Compose Target

Source: https://pullpreview.com/docs/cli

Deploy using the Compose engine with specific file and proxy configurations.

```bash
pullpreview up ./examples/workflow-smoke \
  --name pullpreview-local-compose \
  --deployment-target compose \
  --compose-files docker-compose.yml \
  --compose-options=--build \
  --proxy-tls web:8080
```

--------------------------------

### Deploy Multiple Preview Environments

Source: https://pullpreview.com/docs/faq

Use the deployment_variant input to create independent environments from a single PR.

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

--------------------------------

### Deploy with Helm Target

Source: https://pullpreview.com/docs/cli

Deploy using the Helm engine, requiring chart definitions and proxy TLS settings.

```bash
pullpreview up ./examples/openproject \
  --name pullpreview-local-helm \
  --deployment-target helm \
  --chart ./chart \
  --chart-values values-preview.yaml \
  --chart-set 'baseUrl={{pullpreview_url}}' \
  --proxy-tls-hosts 'nextcloud.{{pullpreview_public_dns}},keycloak.{{pullpreview_public_dns}}' \
  --proxy-tls '{{release_name}}-web:80'
```

--------------------------------

### Reconcile Deployments with github-sync

Source: https://pullpreview.com/docs/cli

Synchronize local deployment state with repository status, optionally forcing a specific action.

```bash
pullpreview github-sync ./path/to/app
pullpreview github-sync ./path/to/app --force-action up
pullpreview github-sync ./path/to/app --force-action down
```

--------------------------------

### Run framework seeds as a Compose service

Source: https://pullpreview.com/docs/seeding-data

Use a one-off Compose service with a restart policy to execute framework-specific seed commands during the first deployment.

```yaml
services:
  db:
    image: postgres
  web:
    build: .
    command: bundle exec rails s
    depends_on: [db, seeder]
  seeder:
    command: bundle exec rails db:seed
    restart: on-failure
    depends_on: [db]
```

--------------------------------

### Preview hostname format

Source: https://pullpreview.com/docs/https-and-domains

The structure of the generated preview hostname.

```text
pr-<pr-number>-<branch>-ip-<dashed-public-ip>.<dns>
```

--------------------------------

### Deploying a Repository-based Helm Chart

Source: https://pullpreview.com/docs/deployment-targets

Configures a deployment using a chart from a remote repository with specific set values and proxy TLS settings.

```yaml

- 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 }}

```

--------------------------------

### Restore a production dump via SSH

Source: https://pullpreview.com/docs/seeding-data

Manually copy and restore a database dump to the preview server using scp and docker compose exec.

```bash
scp my-dump.gz ec2-user@SERVER_IP:/tmp/
zcat /tmp/my-dump.gz | docker compose exec -u postgres db pg_restore -d DBNAME
```

--------------------------------

### Run conditional migrations using PULLPREVIEW_FIRST_RUN

Source: https://pullpreview.com/docs/pre-script

Use the PULLPREVIEW_FIRST_RUN environment variable to distinguish between initial environment creation and subsequent deployments for tasks like database migrations.

```bash
#!/usr/bin/env bash
set -euo pipefail


# /etc/pullpreview/env has already been sourced by PullPreview,
# so PULLPREVIEW_* variables are available here.


if [ "${PULLPREVIEW_FIRST_RUN:-}" = "true" ]; then
  echo "First run for ${PULLPREVIEW_URL} — running migrations"
  docker compose run --rm web bin/rails db:prepare
else
  echo "Subsequent run — running migrations only"
  docker compose run --rm web bin/rails db:migrate
fi
```

--------------------------------

### Hetzner Cloud Deployment Workflow

Source: https://pullpreview.com/docs/workflow-examples

A GitHub Actions workflow configured to deploy PullPreview environments on Hetzner Cloud using specific instance types and regions.

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


permissions:
  contents: read
  pull-requests: write


jobs:
  deploy:
    if: github.event_name == 'schedule' || github.event.label.name == 'pullpreview' || contains(github.event.pull_request.labels.*.name, 'pullpreview')
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v5
      - uses: pullpreview/action@v6
        with:
          admins: "@collaborators/push"
          provider: hetzner
          app_path: .
          region: nbg1
          image: ubuntu-24.04
          instance_type: cpx22
          default_port: 80
          compose_files: docker-compose.yml
          proxy_tls: web:80
          ttl: 1h
        env:
          HCLOUD_TOKEN: "${{ secrets.HCLOUD_TOKEN }}"
          HETZNER_CA_KEY: "${{ secrets.HETZNER_CA_KEY }}"
```

--------------------------------

### Deploying a Local Helm Chart

Source: https://pullpreview.com/docs/deployment-targets

Configures a deployment using a local chart path, including custom values files and additional proxy TLS hostnames.

```yaml

- 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 }}

```

--------------------------------

### Configure custom domain

Source: https://pullpreview.com/docs/https-and-domains

Sets a custom domain suffix for preview URLs after delegating the subdomain via NS records.

```yaml
with:
  dns: preview.example.com
```

--------------------------------

### Define multiple preview environments in GitHub Actions

Source: https://pullpreview.com/docs/multiple-environments

Uses the deployment_variant input to distinguish between multiple environments while sharing the same label for lifecycle management.

```yaml
name: pullpreview_multi_env
on:
  schedule:
    - cron: "45 0 * * *"
  pull_request:
    types: [labeled, unlabeled, synchronize, closed, reopened, opened]


jobs:
  deploy_env1:
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule' || github.event.label.name == 'pullpreview-multi-env' || contains(github.event.pull_request.labels.*.name, 'pullpreview-multi-env')
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v6
      - uses: pullpreview/action@v6
        with:
          deployment_variant: env1
          label: pullpreview-multi-env
          admins: crohr
          app_path: ./examples/wordpress
          instance_type: micro
          registries: docker://${{ secrets.GHCR_PAT }}@ghcr.io
        env:
          AWS_ACCESS_KEY_ID: "${{ secrets.AWS_ACCESS_KEY_ID }}"
          AWS_SECRET_ACCESS_KEY: "${{ secrets.AWS_SECRET_ACCESS_KEY }}"


  deploy_env2:
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule' || github.event.label.name == 'pullpreview-multi-env' || contains(github.event.pull_request.labels.*.name, 'pullpreview-multi-env')
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v6
      - uses: pullpreview/action@v6
        with:
          deployment_variant: env2
          label: pullpreview-multi-env
          admins: crohr
          app_path: ./examples/wordpress
          instance_type: micro
          registries: docker://${{ secrets.GHCR_PAT }}@ghcr.io
        env:
          AWS_ACCESS_KEY_ID: "${{ secrets.AWS_ACCESS_KEY_ID }}"
          AWS_SECRET_ACCESS_KEY: "${{ secrets.AWS_SECRET_ACCESS_KEY }}"
```

--------------------------------

### Define registry credential URI format

Source: https://pullpreview.com/docs/private-registries

The standard format for registry credentials using the docker:// scheme.

```text
docker://username:password@registry.host
```

--------------------------------

### Set DNS suffix

Source: https://pullpreview.com/docs/https-and-domains

Sets the domain suffix for generated preview hostnames.

```yaml
with:
  dns: my.preview.run   # default
```

--------------------------------

### Reference environment variables in Docker Compose

Source: https://pullpreview.com/docs/environment-variables

Use the ${PULLPREVIEW_URL} syntax within a docker-compose.yml file to inject the live preview URL into application services.

```yaml
services:
  web:
    image: myapp
    environment:
      APP_URL: ${PULLPREVIEW_URL}
```

--------------------------------

### Use built-in alternative domain

Source: https://pullpreview.com/docs/https-and-domains

Uses an alternative domain to avoid Let's Encrypt rate limits on the default domain.

```yaml
with:
  proxy_tls: web:80
  dns: rev1.click
```

--------------------------------

### Enable TLS termination

Source: https://pullpreview.com/docs/https-and-domains

Configures Caddy to handle HTTPS termination for a specific service and port.

```yaml
with:
  proxy_tls: web:80
```

--------------------------------

### Restore S3 dump on first run

Source: https://pullpreview.com/docs/seeding-data

Configure a seeder service to restore a mounted database dump only when PULLPREVIEW_FIRST_RUN is true.

```yaml
services:
  seeder:
    image: postgres
    command: '[ "$PULLPREVIEW_FIRST_RUN" = "true" ] && pg_restore -h db -d DBNAME /dumps/latest-dump.gz'
    restart: on-failure
    volumes:
      - ./dumps:/dumps
    depends_on: [db]
```

--------------------------------

### Configure GitHub Actions for AWS OIDC

Source: https://pullpreview.com/docs/aws-setup

Use this workflow configuration to enable OIDC-based authentication for AWS, replacing long-lived access keys.

```yaml
permissions:
  id-token: write
  contents: read
  pull-requests: write


steps:
  - uses: actions/checkout@v6
  - name: Configure AWS credentials (OIDC)
    uses: aws-actions/configure-aws-credentials@v5
    with:
      role-to-assume: arn:aws:iam::123456789012:role/pullpreview
      aws-region: us-east-1
  - uses: pullpreview/action@v6
```

--------------------------------

### Standard PullPreview v6 Workflow

Source: https://pullpreview.com/docs/migrating-v5-to-v6

The canonical workflow configuration for v6, utilizing an if-guard to handle scheduled cleanups and PR-based deployment events.

```yaml

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


jobs:
  deploy:
    if: github.event_name == 'schedule' || github.event.label.name == 'pullpreview' || contains(github.event.pull_request.labels.*.name, 'pullpreview')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: pullpreview/action@v6

```

--------------------------------

### Minimal PullPreview Lightsail workflow

Source: https://pullpreview.com/docs/getting-started

A standard GitHub Actions workflow file for deploying PullPreview environments on AWS Lightsail.

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


permissions:
  contents: read
  pull-requests: write


jobs:
  deploy:
    if: github.event_name == 'schedule' || github.event.label.name == 'pullpreview' || contains(github.event.pull_request.labels.*.name, 'pullpreview')
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v5
      - uses: pullpreview/action@v6
        with:
          admins: "@collaborators/push"
          provider: lightsail
          app_path: .
          instance_type: nano
          default_port: 80
          compose_files: docker-compose.yml
          proxy_tls: web:80
          ttl: 24h
        env:
          AWS_ACCESS_KEY_ID: "${{ secrets.AWS_ACCESS_KEY_ID }}"
          AWS_SECRET_ACCESS_KEY: "${{ secrets.AWS_SECRET_ACCESS_KEY }}"
          AWS_REGION: "us-east-1"
```

--------------------------------

### Load Environment Variables

Source: https://pullpreview.com/docs/cli

Utility command to export variables from a .env file into the current shell session.

```bash
set -a; . ./.env; set +a
```

--------------------------------

### Configure AWS Lightsail credentials

Source: https://pullpreview.com/docs/configuration

Set these environment variables on the pullpreview/action step to authenticate with AWS Lightsail.

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

--------------------------------

### Mirroring Workflow for Long-Lived Branch Previews

Source: https://pullpreview.com/docs/migrating-v5-to-v6

A separate workflow to sync a source branch to a dedicated preview branch, enabling continuous deployment via a long-lived pull request.

```yaml

name: Sync preview branch
on:
  push:
    branches: [main]


permissions:
  contents: write


jobs:
  sync-preview-branch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
          git checkout -B preview-main origin/main
          git push --force origin preview-main

```

--------------------------------

### Configure Hetzner Cloud credentials

Source: https://pullpreview.com/docs/configuration

Provide the HCLOUD_TOKEN and the required SSH CA private key for Hetzner Cloud deployments.

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

--------------------------------

### Automate dump restoration in GitHub Actions

Source: https://pullpreview.com/docs/seeding-data

Download a database dump from S3 in your workflow before the PullPreview deployment step.

```yaml
# .github/workflows/pullpreview.yml — extra step before the pullpreview step
- name: Fetch dump
  env:
    AWS_ACCESS_KEY_ID: "${{ secrets.AWS_ACCESS_KEY_ID }}"
    AWS_SECRET_ACCESS_KEY: "${{ secrets.AWS_SECRET_ACCESS_KEY }}"
  run: |
    mkdir -p dumps/
    aws s3 cp s3://my-backup-bucket/latest-dump.gz dumps/
```

--------------------------------

### Configure pre_script in GitHub Actions

Source: https://pullpreview.com/docs/pre-script

Specify the path to the bash script relative to the app_path within the PullPreview action configuration.

```yaml
- uses: pullpreview/action@v6
  with:
    pre_script: ./bin/preview-setup.sh
```

--------------------------------

### Configure License Key in GitHub Actions

Source: https://pullpreview.com/docs/faq

Set the license key as a workflow input using a GitHub Actions secret.

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

--------------------------------

### Generate Hetzner SSH CA key

Source: https://pullpreview.com/docs/getting-started

Use this command to generate the required PEM-encoded RSA private key for Hetzner Cloud authentication.

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

--------------------------------

### Define token-only registry URI

Source: https://pullpreview.com/docs/private-registries

Format for authenticating using only a token, useful for registries like GHCR.

```text
docker://TOKEN@registry.host
```

--------------------------------

### Configure Helm proxy hosts

Source: https://pullpreview.com/docs/https-and-domains

Defines additional public hostnames for Helm deployments using the proxy_tls_hosts input.

```yaml
with:
  deployment_target: helm
  proxy_tls: "{{ release_name }}-web:80"
  proxy_tls_hosts: "admin.{{ pullpreview_public_dns }}"
```

--------------------------------

### Define Least-Privilege IAM Policy

Source: https://pullpreview.com/docs/aws-setup

Apply this policy to the IAM role to restrict access exclusively to AWS Lightsail resources.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": ["lightsail:*"], "Resource": "*" }
  ]
}
```
Tokens:
Raw