# GitHub Actions

Run Buddy Visual Tests from GitHub Actions workflows and block merges until visual changes are approved.

You can create visual test sessions from GitHub Actions workflows - useful when your CI lives in GitHub but you want Buddy's rendering matrix, diffing, and review flow. Buddy reports the session result back to GitHub as a commit status, so you can gate merges on visual approval.

## Secret configuration in GitHub

To use `BUDDY_VT_TOKEN` in GitHub Actions, add it as a secret in your repository:

1. Navigate to **Settings** > **Secrets and variables** > **Actions** in your GitHub repository
2. Click **New repository secret**
3. Enter the name: `BUDDY_VT_TOKEN`
4. Enter the token from the [suite settings](/docs/tests/visual-tests/suite-settings.md) in Buddy
5. Click **Add secret**

## Example GitHub Actions workflow

Install the `bdy` CLI in the job and wrap your test command with `session create`:

```yaml
name: Visual Tests
on: [push, pull_request]

jobs:
  visual-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install dependencies
        run: npm ci
      - name: Install Buddy CLI
        run: npm i -g bdy
      - name: Run visual tests
        env:
          BUDDY_VT_TOKEN: ${{ secrets.BUDDY_VT_TOKEN }}
        run: bdy tests visual session create "npx playwright test"
```

For a Storybook suite, replace the last step with:

```yaml
      - name: Upload Storybook
        env:
          BUDDY_VT_TOKEN: ${{ secrets.BUDDY_VT_TOKEN }}
        run: |
          npm run build-storybook
          cd storybook-static && bdy tests visual upload
```

## Blocking merges until changes are approved

Buddy sends a commit status to GitHub for each session. A session with unreviewed visual changes reports as pending, so you can enforce review with a branch protection rule:

1. In your GitHub repository, go to **Settings** > **Branches** and edit the protection rule for your target branch
2. Enable **Require status checks to pass before merging**
3. Add the Buddy visual tests status check to the required list

With this in place, a pull request that introduces visual changes cannot be merged until someone approves the session in Buddy - see [Reviewing & Approvals](/docs/tests/visual-tests/reviewing-approvals.md).


---
Original source: https://buddy.works/docs/tests/visual-tests/running-visual-tests/github-actions