Getting Started

0. Prerequisite

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 your Compose file requires additional files to boot, which are not committed to your Git repository (e.g. .env file with secrets), then you can very easily handle this case by running a script before PullPreview is triggered, and/or committing another Compose file to be used with PullPreview (see https://docs.docker.com/compose/extends/). The Example Workflows section has examples for this scenario and others.

1. Create the label

That step is simple: Create the pullpreview label in your repository, and assign whatever color you like.

2. Setup the AWS credentials in your repository

Get the required AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY secrets from your AWS account, and 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 Advanced AWS Configuration for how to create a user with a more restricted policy.

3. Setup 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.

Here is an example that allows SSH access for two users into the preview environments, as well as marking the master branch as always on:

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

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
    - uses: actions/checkout@v2
    - uses: pullpreview/action@v3
      with:
        admins: crohr,other-github-user
        always_on: master
      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.

PullPreview is now ready to be used: open a PR, add the pullpreview label, and you're done.