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 AWS credentials

PullPreview provisions Lightsail instances in your AWS account.

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.

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: automatic HTTPS termination with Let's Encrypt
          # proxy_tls: web:80
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: us-east-1

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.