Gaffer

Gaffer

GitHub Action

Automatically upload test reports from GitHub Actions.

The official Gaffer Uploader GitHub Action makes it easy to automatically upload test reports from your CI workflows.

Prerequisites

Setup

1. Add your API key as a secret

  1. Go to your GitHub repository
  2. Navigate to Settings → Secrets and variables → Actions
  3. Click New repository secret
  4. Name: GAFFER_API_KEY
  5. Value: Your Gaffer project API key

2. Add the upload step to your workflow

Add the Gaffer uploader step after your test step. Use if: always() to ensure reports are uploaded even when tests fail.

Inputs

Input Required Description
gaffer_api_key Yes Your Gaffer project API key
report_path Yes Path to the report file or directory to upload
api_endpoint No Custom API endpoint URL (for staging/preview environments)
commit_sha No Git commit SHA to associate with the test run
branch No Git branch name to associate with the test run
test_framework No Test framework used (e.g., playwright, jest, pytest)
test_suite No Name of the test suite (e.g., unit, e2e)

Examples

Basic Usage

.github/workflows/test.yml 
name: Tests

on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Upload to Gaffer
        uses: gaffer-sh/gaffer-uploader@v1
        if: always()
        with:
          gaffer_api_key: ${{ secrets.GAFFER_API_KEY }}
          report_path: ./test-results
          commit_sha: ${{ github.sha }}
          branch: ${{ github.ref_name }}

Playwright Example

A complete example for Playwright tests:

.github/workflows/playwright.yml 
name: Playwright Tests

on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v3
        with:
          version: 9

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install

      - name: Install Playwright browsers
        run: pnpm exec playwright install --with-deps

      - name: Run Playwright tests
        run: pnpm exec playwright test

      - name: Upload Playwright Report to Gaffer
        uses: gaffer-sh/gaffer-uploader@v1
        if: always()
        with:
          gaffer_api_key: ${{ secrets.GAFFER_API_KEY }}
          report_path: ./playwright-report
          commit_sha: ${{ github.sha }}
          branch: ${{ github.ref_name }}
          test_framework: playwright
          test_suite: e2e

Pull Request Workflow

For pull request workflows, use github.head_ref to get the correct branch name:

.github/workflows/pr.yml 
name: PR Tests

on:
  pull_request:
    branches: [main]

env:
  branch_name: ${{ github.head_ref || github.ref_name }}

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        run: npm test

      - name: Upload to Gaffer
        uses: gaffer-sh/gaffer-uploader@v1
        if: always()
        with:
          gaffer_api_key: ${{ secrets.GAFFER_API_KEY }}
          report_path: ./test-results
          commit_sha: ${{ github.event.pull_request.head.sha }}
          branch: ${{ env.branch_name }}
          test_framework: jest
          test_suite: unit

Tip: The if: always() condition is important! Without it, the upload step will be skipped when tests fail - which is usually when you need the report the most.

Troubleshooting

Report not uploading

  • Verify the report_path points to the correct file or directory
  • Check that your API key secret is named exactly GAFFER_API_KEY
  • Ensure if: always() is set so the step runs even when tests fail

Wrong branch showing

For pull request workflows, use github.head_ref || github.ref_name pattern to get the correct source branch name.

Next Steps