GitHub Action that deploys previews of pull requests to GitHub Pages. Works on any repository with a GitHub Pages site.

Features:

• Creates and deploys previews of pull requests to your GitHub Pages site
• Leaves a comment on the pull request with a link to the preview so that you and your team can collaborate on new features faster
• Updates the deployment and the comment whenever new commits are pushed to the pull request
• Cleans up after itself — removes deployed previews when the pull request is closed
• Can be configured to override any of these behaviours

Preview URLs look like this: https://[owner].github.io/[repo]/pr-preview/pr-[number]/

Pictured: #1

This Action does not currently support deploying previews for PRs from forks, but will do so in the upcoming v2.

A GitHub Actions workflow is required to use this Action.

All the workflow needs to do first is checkout the repository and build the Pages site.

First, ensure that your repository is configured to have its GitHub Pages site deployed from a branch, by setting the source for the deployment under Settings > Pages of your repository to Deploy from branch:

Pictured: Repository Pages settings at /settings/page

The gh-pages branch is used for GitHub Pages deployments by convention, and will be used in examples here as well.

If your GitHub pages site is deployed from the gh-pages branch, built with e.g. an npm script to the ./build/ dir, and you're happy with the default settings, usage is very simple:

# .github/workflows/preview.yml
name: Deploy PR previews

on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed

concurrency: preview-${{ github.ref }}

jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install and Build
        if: github.event.action != 'closed' # You might want to skip the build if the PR has been closed
        run: |
          npm install
          npm run build

      - name: Deploy preview
        uses: rossjrw/pr-preview-action@v1
        with:
          source-dir: ./build/

The following input parameters are provided, which can be passed to the with parameter. All parameters are optional and have a default value.

Several output values are provided to use after this Action in your workflow. To use them, give this Action's step an id and reference the value with ${{ steps.<id>.outputs.<name> }}, e.g.:

# .github/workflows/preview.yml
jobs:
  deploy-preview:
    steps:
      - uses: rossjrw/pr-preview-action@v1
        id: preview-step
      - if: steps.preview-step.outputs.deployment-action == "deploy"
        run: echo "Preview visible at ${{ steps.preview-step.outputs.preview-url }}"

You could use these outputs and input parameter comment: false to write your own sticky comment after the Action has run.

This must be changed in the repository settings by selecting "Read and write permissions" at Settings > Actions > General > Workflow permissions. Otherwise, the Action won't be able to make any changes to your deployment branch.

Be sure to pick the right event types for the pull_request event. It only comes with opened, reopened, and synchronize by default — but this Action assumes by default that the preview should be removed during the closed event, which it only sees if you explicitly add it to the workflow.

If you are using GitHub Actions to deploy your GitHub Pages sites (typically on push to the main branch), there are some actions you should take to avoid the PR preview overwriting the main deployment, or vice-versa.

1. Prevent your main deployment from deleting previews

   If your root directory on the GitHub Pages deployment branch (or docs/ on the main branch) is generated automatically (e.g. on pushes to the main branch, with a tool such as Webpack), you will need to configure it not to remove the umbrella directory (pr-preview/ by default, see configuration below).

   For example, if you are using JamesIves/github-pages-deploy-action to deploy your build, you can implement this using its clean-exclude parameter:

   # .github/workflows/build-deploy-pages-site.yml
   steps:
     ...
     - uses: JamesIves/github-pages-deploy-action@v4
       ...
       with:
         clean-exclude: pr-preview/
         ...

   If you don't do this, your main deployment may delete all of your currently-existing PR previews.

2. Don't force-push your main deployment

   Force-pushing your main deployment will cause it to overwrite any and all files in the deployment location. This will destroy any ongoing preview deployments. Instead, consider adjusting your deployment workflow to rebase or merge your main deployment onto the deployment branch to respect other ongoing deployments.

   For example, if you are using JamesIves/github-pages-deploy-action to deploy your build, be aware that at the time of writing (v4.7.2) it force-pushes new deployments by default. You can disable this by setting its force parameter to false, which will prompt it to rebase new deployments instead of force-pushing them:

   # .github/workflows/build-deploy-pages-site.yml
   steps:
     ...
     - uses: JamesIves/github-pages-deploy-action@v4
       ...
       with:
         force: false
         ...

   This feature was introduced in v4.3.0 of the above Action.

Consider limiting this workflow to run only when relevant files are edited to avoid deploying previews unnecessarily.

I highly recommend setting a concurrency group scoped to each PR using github.ref as above, which should prevent the preview and comment from desynchronising if you are e.g. committing very frequently.

Full example with all default values added:

# .github/workflows/preview.yml
name: Deploy PR previews
concurrency: preview-${{ github.ref }}
on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed
jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm i && npm run build
        if: github.event.action != 'closed'
      - uses: rossjrw/pr-preview-action@v1
        with:
          source-dir: .
          preview-branch: gh-pages
          umbrella-dir: pr-preview
          action: auto

...and an accompanying main deployment workflow:

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm i && npm run build
      - uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: .
          branch: gh-pages
          clean-exclude: pr-preview
          force: false

If your Pages site is built to build/ and deployed from the docs/ directory on the main branch:

# .github/workflows/preview.yml
steps:
  ...
  - uses: rossjrw/pr-preview-action@v1
    with:
      source-dir: build
      preview-branch: main
      umbrella-dir: docs/pr-preview
      pages-base-path: docs

You should definitely limit this workflow to run only on changes to directories other than docs/, otherwise this workflow will call itself recursively.

Information from the context and conditionals can be used to make more complex decisions about what to do with previews; for example, removing only those associated with unmerged PRs when they are closed:

# .github/workflows/preview.yml
steps:
  ...
  - uses: rossjrw/pr-preview-action@v1
    if: contains(['opened', 'reopened', 'synchronize'], github.event.action)
    with:
      source-dir: ./build/
      action: deploy
  - uses: rossjrw/pr-preview-action@v1
    if: github.event.action == "closed" && !github.event.pull_request.merged
    with:
      source-dir: ./build/
      action: remove

If you want to keep PR previews around forever, even after the associated PR has been closed, you don't want the cleanup behaviour of auto — call deploy and never call remove:

# .github/workflows/everlasting-preview.yml
name: Deploy everlasting PR preview
concurrency: preview-${{ github.ref }}
on:
  pull_request:
    types:
      - opened
      - synchronize
jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm i && npm run build
      - uses: rossjrw/pr-preview-action@v1
        with:
          source-dir: ./build/
          action: deploy

You can use id, with: comment: false, the output values and context variables to construct your own comment to be left on the PR. This example recreates this Action's default comment (complete with HTML spacing jank), but you could change it however you like, use a different commenting Action from the marketplace, etc.

# .github/workflows/preview.yml
name: Deploy PR preview
concurrency: preview-${{ github.ref }}
on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed
env:
  PREVIEW_BRANCH: gh-pages
jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm i && npm run build

      - uses: rossjrw/pr-preview-action@v1
        id: preview-step
        with:
          source-dir: ./build/
          preview-branch: ${{ env.PREVIEW_BRANCH }}
          comment: false

      - uses: marocchino/sticky-pull-request-comment@v2
        if: steps.preview-step.outputs.deployment_action == 'deploy' && env.deployment_status == 'success'
        with:
          header: pr-preview
          message: |
            [PR Preview Action](https://github.com/rossjrw/pr-preview-action) ${{ steps.preview-step.outputs.action-version }}
            :---:
            | <p></p> :rocket: View preview at <br> ${{ steps.preview-step.outputs.preview-url }} <br><br>
            | <h6>Built to branch [`${{ env.PREVIEW_BRANCH }}`](${{ github.server_url }}/${{ github.repository }}/tree/${{ env.PREVIEW_BRANCH }}) at ${{ steps.preview-step.outputs.action-start-time }}. <br> Preview will be ready when the [GitHub Pages deployment](${{ github.server_url }}/${{ github.repository }}/deployments) is complete. <br><br> </h6>

      - uses: marocchino/sticky-pull-request-comment@v2
        if: steps.preview-step.outputs.deployment_action == 'remove' && env.deployment_status == 'success'
        with:
          header: pr-preview
          message: |
            [PR Preview Action](https://github.com/rossjrw/pr-preview-action) ${{ steps.preview-step.outputs.action-version }}
            :---:
            Preview removed because the pull request was closed.
            ${{ steps.preview-step.outputs.action-start-time }}

Big thanks to the following:

• shlinkio/deploy-preview-action (MIT), prior art that informed the direction of this Action
• JamesIves/github-pages-deploy-action (MIT), used by this Action to deploy previews
• marocchino/sticky-pull-request-comment (MIT), used by this Action to leave a sticky comment on pull requests
• Everyone who has contributed to this Action