Back to Documentation

GitHub Actions Integration

Setup

To integrate Qualigate with GitHub Actions, you need to add your API key as a repository secret:

  1. Go to your GitHub repository → Settings → Secrets and variables → Actions
  2. Click "New repository secret"
  3. Name: QUALIGATE_API_KEY
  4. Value: Your API key from Qualigate dashboard
  5. Click "Add secret"

Optionally, add QUALIGATE_PROJECT_ID as a secret if you want to reference it in workflows.

Basic Workflow

Create a workflow file at .github/workflows/e2e-tests.yml:

yaml
name: E2E Tests
on:
  pull_request:
    branches: [main]

jobs:
  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Run Qualigate Tests
        run: |
          npx qualigate run --project ${{ secrets.QUALIGATE_PROJECT_ID }} --json
        env:
          QUALIGATE_API_KEY: ${{ secrets.QUALIGATE_API_KEY }}

This workflow runs all CI-configured tests for your project on every pull request. The job will fail if any tests fail, blocking the PR from being merged.

Advanced: Running Specific Suites

Run different test suites for different branches or events:

yaml
name: E2E Tests
on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  smoke-tests:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - name: Run Smoke Tests
        run: npx qualigate run --suite ${{ secrets.QUALIGATE_SMOKE_SUITE_ID }}
        env:
          QUALIGATE_API_KEY: ${{ secrets.QUALIGATE_API_KEY }}

  full-regression:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Run Full Regression
        run: npx qualigate run --project ${{ secrets.QUALIGATE_PROJECT_ID }}
        env:
          QUALIGATE_API_KEY: ${{ secrets.QUALIGATE_API_KEY }}

Advanced: Adding PR Context

Include PR metadata in your test runs for better traceability:

bash
curl -X POST https://qualigate.app/api/v1/trigger \
  -H "Authorization: Bearer $QUALIGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "context": {
      "source": "github-actions",
      "pr_number": "'"$PR_NUMBER"'",
      "sha": "'"$GITHUB_SHA"'",
      "branch": "'"$GITHUB_HEAD_REF"'",
      "repository": "'"$GITHUB_REPOSITORY"'"
    }
  }'

Full workflow example with context:

yaml
name: E2E Tests with Context
on:
  pull_request:
    branches: [main]

jobs:
  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Extract PR number
        id: pr
        run: echo "number=${{ github.event.pull_request.number }}" >> $GITHUB_OUTPUT

      - name: Trigger Qualigate Tests
        run: |
          curl -X POST https://qualigate.app/api/v1/trigger \
            -H "Authorization: Bearer ${{ secrets.QUALIGATE_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "project_id": "${{ secrets.QUALIGATE_PROJECT_ID }}",
              "context": {
                "source": "github-actions",
                "pr_number": "${{ steps.pr.outputs.number }}",
                "sha": "${{ github.sha }}",
                "branch": "${{ github.head_ref }}",
                "repository": "${{ github.repository }}"
              }
            }'

Advanced: Matrix Strategy

Run different test suites in parallel using a matrix:

yaml
name: E2E Test Matrix
on:
  pull_request:
    branches: [main]

jobs:
  e2e-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        suite:
          - name: "Smoke Tests"
            id: "suite-smoke-id"
          - name: "Auth Tests"
            id: "suite-auth-id"
          - name: "Payment Tests"
            id: "suite-payment-id"
    steps:
      - name: Run ${{ matrix.suite.name }}
        run: npx qualigate run --suite ${{ matrix.suite.id }}
        env:
          QUALIGATE_API_KEY: ${{ secrets.QUALIGATE_API_KEY }}

Test Results

Test results are available in the Qualigate dashboard. Each test run includes:

  • Step-by-step execution logs with AI reasoning
  • Screenshots for each action
  • Video recording of the entire test
  • Pass/fail status with detailed error messages if failures occur

You can view test runs in real-time from the Test Runs page, with direct links to specific runs from your CI logs.

Best Practices

  • ✓Run smoke tests on all PRs and full regression on merges to main
  • ✓Use --json flag for programmatic parsing of results
  • ✓Set appropriate timeouts based on your test complexity (default: 600s)
  • ✓Tag test cases with run_on_ci: true to control which tests run
  • ✓Use matrix strategies to parallelize test execution across suites

Troubleshooting

"Unauthorized" error

Check that your QUALIGATE_API_KEY secret is set correctly in GitHub repository settings.

Tests timeout

Increase the --timeout value. Complex tests may take longer than the default 600 seconds.

"npx: command not found"

Ensure Node.js is installed in your GitHub Actions runner. Add a setup-node step before running tests.

Next Steps

Learn more about integrating Qualigate with your workflow: