Sign in or start for free

Deprecated GitHub Actions

Suggest Edits

👍

Covered in this doc

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

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.

Start by adding the PERCY_TOKEN to your repos secrets. 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.

803

Now you can run your tests with Percy (typically percy exec -- [test command]) and send builds to Percy from CI.

🚧

Needed with @percy/agent

If you're currently using @percy/agent (and haven't migrated to the new CLI), you will need to use one of these actions below.

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/checkout@master
      - name: Setup Ruby
        uses: actions/setup-ruby@v1
      - 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/checkout@master
      - name: Setup Ruby
        uses: actions/setup-ruby@v1
      - 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 about 2 years ago