GitHub Actions Integration

Introduction

GitHub Actions is a powerful CI/CD platform built into GitHub that allows you to automate your software development workflows. OtterWise integrates seamlessly with GitHub Actions, making it easy to automatically collect and report code coverage data after your test suite runs.

This integration uses a lightweight bash script uploader that runs as a step in your GitHub Actions workflow, ensuring your code coverage data is sent to OtterWise while maintaining security and privacy.

How It Works

The GitHub Actions integration:

1. Runs your test suite with coverage reporting enabled
2. Uses a bash script to process and upload the coverage data to OtterWise
3. Detects the repository, branch, and commit information automatically
4. Works with all major testing frameworks that can generate coverage reports

Prerequisites

Before setting up the GitHub Actions integration, you'll need:

• A GitHub repository connected to OtterWise
• A test suite that can generate coverage reports (see the supported formats)

Setting Up the Integration

Step 1: Add the OtterWise Token as a Secret

First, you need to add your OtterWise token as a GitHub repository secret:

1. Navigate to your GitHub repository
2. Go to "Settings" > "Secrets and variables" > "Actions"
3. Click "New repository secret"
4. Name: OTTERWISE_TOKEN
5. Value: Your OtterWise token (available in your repository settings in OtterWise)
6. Click "Add secret"

Step 2: Configure Your GitHub Actions Workflow

Add the OtterWise uploader to your GitHub Actions workflow file (e.g., .github/workflows/tests.yml). Make sure it runs after your test suite has completed:

- name: Upload Coverage
  env:
    OTTERWISE_TOKEN: ${{ secrets.OTTERWISE_TOKEN }}
  run: bash <(curl -s https://raw.githubusercontent.com/getOtterWise/bash-uploader/main/uploader.sh)

Step 3: Ensure Proper Git Checkout Depth

For the uploader to properly analyze code changes, you need to set a git checkout depth of at least 2 in your workflow:

steps:
- uses: actions/checkout@v3
  with:
    fetch-depth: 2

Complete GitHub Actions Workflow Example

Here's a complete example of a GitHub Actions workflow for a PHP project using PHPUnit:

name: Tests

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

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
      with:
        fetch-depth: 2

    - name: Set up PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.2'
        coverage: xdebug

    - name: Install dependencies
      run: composer install --prefer-dist --no-progress

    - name: Run tests with coverage
      run: vendor/bin/phpunit --coverage-clover=build/logs/clover.xml

    - name: Upload Coverage
      env:
        OTTERWISE_TOKEN: ${{ secrets.OTTERWISE_TOKEN }}
      run: bash <(curl -s https://raw.githubusercontent.com/getOtterWise/bash-uploader/main/uploader.sh)

Common Test Framework Commands

Here are examples of how to generate compatible coverage reports with popular testing frameworks:

Customizing the Integration

The OtterWise uploader has several options that can be used to customize the integration. You can read more about it on the Bash Uploader page.

Troubleshooting

If you encounter issues with the GitHub Actions integration, check these common problems:

• Coverage file not found: Verify that your test framework is generating the coverage report in the expected location
• Authentication errors: Ensure your OTTERWISE_TOKEN is correctly set in GitHub Secrets
• Git diff issues: Make sure you've set fetch-depth: 2 in your checkout step
• Debug mode: Enable debug output by setting OTTERWISE_DEBUG=true to see detailed information

For further assistance, contact OtterWise support or check our example repository which contains fully working GitHub Actions workflow examples.