Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!

GitHub Actions

👍

Covered in this doc

GitHub actions provided by Percy
Integrating Percy with GitHub actions
percy/exec-action docs
percy/storybook-action docs
percy/snapshot-action docs

GitHub Actions makes it easy to automate all your software workflows. Percy provides a few GitHub actions to make building with GitHub actions as easy as possible:

Configuring environment variables


📘

Keep your Percy token secret

Anyone with access to your token can add builds to your project, though they cannot read data.

No matter the action you're using, you will need to start by configuring the PERCY_TOKEN. PERCY_TOKEN is your project-specific, write-only API token. It can be found in your Percy project settings and add it to your GitHub project secrets.

In your GitHub project's settings, go to Settings > Secrets

Then set PERCY_TOKEN to the write-only token from your Percy project. This token can be found in each Percy project's settings.

exec-action

Checkout the action on GitHub
In the GitHub Marketplace

The Percy exec-action should be used with any Percy SDK that uses percy exec. This action acts as a wrapper around the percy exec CLI command, so all you need to provide is the CLI command you use to launch your tests.

🚧

SDK setup required

Make sure you have setup one of the Percy's SDKs before getting started with the GitHub exec-action

Quick start

To use the Percy exec GitHub action you will need to add a new step to your actions config using the percy/exec-action action. exec-action has one required input: the command to run your tests. You will also need to set your PERCY_TOKEN in your GitHub projects settings.

Below is a sample config that runs Cypress with Percy. If you don't have an existing GitHub workflow file, you could place this example in <project_root>/.github/workflows/ci.yml:

name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]
      - name: Install
        run: yarn
      - name: Percy Test
        uses: percy/[email protected]
        with:
          command: "cypress run"
        env:
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]
      - name: Install
        run: yarn
      - name: Percy Test
        uses: percy/[email protected]
        with:
          command: "cypress run"
          custom-command: './tests/run-tests.sh'
          exec-flags: "-t 150 -h cdn.example.com"
          verbose: true
          silence: false
          passthrough: false
          working-directory: "./client"
        env:
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

Inputs

  • command - Your test suites CLI command
  • custom-command - Run your own shell command
  • exec-flags - Flags to pass to the percy exec command. See our CLI for the possible flags to pass.
  • working-directory (default: ./) - The directory for the commands to execute in
  • silence - Silence the logging from Percy
  • verbose - Verbose debug logging from Percy
  • passthrough - Set Percy env vars, but do not execute commands

storybook-action

Checkout the action on GitHub
In the GitHub Marketplace

🚧

SDK setup required

Make sure you have setup the Percy Storybook SDK before getting started with the GitHub storybook-action

The Percy storybook-action should be used with only the Percy Storybook SDK.

Quick start

To use the Percy exec GitHub action you will need to add a new step to your actions config using the percy/storybook-action action. Using the default settings, you can just use the action directly. You will also need to set your PERCY_TOKEN in your GitHub projects settings.

This is a sample config using the default setup. If you don't have an existing GitHub workflow file, you could place this example in <project_root>/.github/workflows/ci.yml:

name: CI
on: [push, pull_request]
jobs:
  default:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]
      - name: Install
        run: yarn
      - name: Percy Test
        uses: percy/[email protected]
        env:
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
name: CI
on: [push, pull_request]
jobs:
  default:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]
      - name: Install
        run: yarn
      - name: Percy Test
        uses: percy/[email protected]
        with:
          percy-flags: "--widths=320,1280"
          storybook-flags: "-c /configs/.storybook"
          working-directory: "./example-storybook"
        env:
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

Custom commands

This is a setup that passes a custom command, which allows for any configuration:

name: CI
on: [push, pull_request]
jobs:
  custom_command:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]
      - name: Install
        run: yarn
      - name: Percy Test
        uses: percy/[email protected]
        with:
          custom-command: 'yarn storybook:percy'
        env:
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

Inputs

  • storybook-flags - Flags to pass to the build-storybook CLI command
  • percy-flags - Flags to pass to the percy-storybook CLI command
  • working-directory (default: ./) - The directory for the commands to execute in
  • custom-command - Your own CLI command to build storybook & run percy-storybook. Useful for when you want complete control over what is ran.

snapshot-action

Checkout the action on GitHub
In the GitHub Marketplace

The snapshot-action allows you to visually test any static site in GitHub Actions. It uses our Static sites SDK under the hood.

Quick start

To use the Percy static sites GitHub action you will need to add a new step to your actions config using the percy/snapshot-action action. You will need to specify the build-directory which your static site builds to. You will also need to set your PERCY_TOKEN in your GitHub projects settings.

This is a sample config using the default setup. If you don't have an existing GitHub workflow file, you could place this example in <project_root>/.github/workflows/ci.yml:

name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]
      - name: Setup Ruby
        uses: actions/[email protected]
      - name: Install
        run: bundle install
      - name: Build
        run: bundle exec jekyll build
      - name: Default test
        uses: percy/[email protected]
        with:
          build-directory: "_site"
        env:
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]
      - name: Setup Ruby
        uses: actions/[email protected]
      - name: Install
        run: bundle install
      - name: Build
        run: bundle exec jekyll build
      - name: Default test
        uses: percy/[email protected]
        with:
          build-directory: "_site"
          flags: "--base-url /marketing"
          working-directory: "./static-site"
          silence: false
          verbose: true
        env:
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

Inputs

  • build-directory - The directory where your static site outputs its build to
  • flags - Flags to pass to the percy snapshot CLI command
  • working-directory (default: ./) - The directory for the commands to execute in
  • silence - Silence the logging from Percy
  • verbose - Verbose debug logging from Percy

Updated 7 months ago


GitHub Actions


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.