Getting Started

1. Have a Docker Compose file in your repository

Make sure your application has a valid Docker Compose file that can boot a complete environment. All versions are supported. By default it assumes a compose file in the root of your repository, named docker-compose.yml.

If you don't have one and just want to test the action, you can use the self-contained example below that deploys a simple sinatra Ruby server backed by a PostgreSQL database, with SSL termination:

# docker-compose.pullpreview.yml
services:
  # easily set up SSL termination
  proxy:
    image: caddy:2
    restart: unless-stopped
    command: "caddy reverse-proxy --from '${PULLPREVIEW_URL}' --to web:4567"
    depends_on:
      - web
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "/data"

  # simple ruby web server for demo purposes, which connects to a postgres DB
  web:
    restart: unless-stopped
    depends_on:
      - db
    build:
      context: .
      dockerfile_inline: |
        FROM ruby:3.2
        RUN gem install sinatra pg puma
        CMD ruby -rsinatra -rpg -rpuma \
          -e'get("/"){ "Hey PullPreview user, here is the postgres version: #{PG.connect(ENV["PGURI"]).exec("SELECT VERSION()").getvalue(0,0)}" }'
        EXPOSE 4567
    environment:
      PGURI: "postgres://postgres:p4ssw0rd@db/postgres"
      APP_ENV: production

  db:
    restart: unless-stopped
    image: postgres:13
    environment:
      POSTGRES_PASSWORD: p4ssw0rd

2. Create the pullpreview label

That step is simple: create the pullpreview label in your repository (use whatever color you like). You can do this from the GitHub UI, in the "Issues" of your repository.

3. Setup the AWS credentials in your repository

PullPreview launches your environments on AWS Lightsail servers. Therefore you need to get the required AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY secrets that will allow access to create those resources in your AWS account.

Once you have the credentials, add them to your repository Settings on GitHub, under the Secrets section. You can name the secrets as you please, just make sure to use the same name in the workflow file that you'll create in the next step.

The simplest way to get started is to create an IAM user with full admin privileges (use the existing AWS managed policy for that), although we recommend you have a look at Recommended AWS Configuration for how to create a user with a more restricted policy.

4. Add the PullPreview workflow

For PullPreview to be triggered by GitHub, you need to add it as a workflow into your repository, under the path .github/workflows/pullpreview.yml. Once created, do not forget to commit and push your changes to your repository.

Here is an example that enables PullPreview and specifies that GitHub users crohr and other-github-user will have SSH access into the preview environments:

# .github/workflows/pullpreview.yml
name: PullPreview
on:
  pull_request:
    types: [labeled, unlabeled, synchronize, closed, reopened]

jobs:
  deploy:
    permissions:
      contents: read # to fetch code (actions/checkout)
      deployments: write # to delete deployments
      pull-requests: write # to remove labels
      statuses: write # to create commit status
    name: deploy
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
    - uses: actions/checkout@v2
    - uses: pullpreview/action@{actionVersion}
      # see https://github.com/pullpreview/action/wiki/Inputs
      with:
        admins: crohr,other-github-user
        compose_files: docker-compose.pullpreview.yml
      env:
        AWS_ACCESS_KEY_ID: "${{ secrets.AWS_ACCESS_KEY_ID }}"
        AWS_SECRET_ACCESS_KEY: "${{ secrets.AWS_SECRET_ACCESS_KEY }}"
        AWS_REGION: "us-east-1"

More examples can be found under Workflow Examples.

5. Deploy!

PullPreview is now ready to be used: open a pull request with the new workflow and docker-compose file, add the pullpreview label, and you should see a deployment up and running a few minutes later.