CI/CD Integration with GitHub Actions

Automating your Drift test suite within a CI/CD pipeline ensures that your API implementation never deviates from its specification. This guide demonstrates how to set up a GitHub Actions workflow to run Drift tests on every pull request.

1. Prerequisites

Before setting up the workflow, ensure your repository contains:

• Your API specification (e.g., openapi.yaml).
• Your Drift test manifest (yaml) and any associated datasets or Lua scripts.
• A way to start your API provider locally within the CI environment (e.g., a Docker container or an npm start command).

2. GitHub Actions Workflow Template

Create a file at .github/workflows/drift-tests.yml. This workflow downloads the Drift binary, starts your service, and executes the test suite.

name: API Contract Tests

on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]

jobs:
  drift-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Download and Install Drift
        run: |
          wget [https://download.pactflow.io/Drift/latest/linux-x86_64.zip](https://download.pactflow.io/Drift/latest/linux-x86_64.zip)
          unzip linux-x86_64.zip
          # Add Drift to the path
          echo "$(pwd)" >> $GITHUB_PATH

      - name: Start API Provider
        run: |
          npm install
          npm start & 
          # Give the server a few seconds to initialize
          sleep 5

      - name: Run Drift Tests
        run: |
          drift --test-files project-demo/yaml \
                --server-url http://localhost:8080 \
                --output-dir ./drift-results

      - name: Archive Test Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: drift-junit-report
          path: ./drift-results

3. Configuring the JUnit Reporter

To get the most out of your CI environment, ensure the junit-output plugin is enabled in your yaml. This allows GitHub to display test results in a standardized format.

# yaml
plugins:
  - name: oas
  - name: junit-output # Enables XML report generation

4. Handling Failures

If a test fails—meaning your code does not match the OpenAPI spec—the Drift command will exit with a non-zero status code. This automatically fails the GitHub Action, preventing the "drifting" code from being merged into your main branch.

Common CI Failures:

• Schema Mismatch: The implementation returned a field type (e.g., String) that differs from the spec (e.g., Integer).
• Missing Required Fields: The response body is missing a field marked as required in the OpenAPI file.
• Incorrect Status Codes: The API returned a 500 error when a 200 was expected by the contract.

5. Environment-Specific Configuration

For more complex environments, you can override configuration values using environment variables with the Drift_ prefix.

      - name: Run Drift Tests with Custom Log Level
        env:
          LOG_LEVEL: DEBUG
        run: drift --test-files project-demo/yaml --server-url ${{ secrets.STAGING_URL }}