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 the official OtterWise GitHub Action 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 the official OtterWise GitHub Action to process and upload the coverage data
3. Detects the repository, branch, and commit information automatically
4. Works with all major testing frameworks that can generate coverage reports

OtterWise provides a dedicated GitHub Action that makes integration seamless and eliminates the need for bash script downloads.

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 GitHub Action to your workflow file (e.g., .github/workflows/tests.yml). Make sure it runs after your test suite has completed:

- name: Upload Coverage to OtterWise
  uses: getOtterWise/github-action@v1
  with:
    token: ${{ secrets.OTTERWISE_TOKEN }}

The action will automatically detect your coverage file in standard locations. If you need to specify a custom location, use the file parameter:

- name: Upload Coverage to OtterWise
  uses: getOtterWise/github-action@v1
  with:
    token: ${{ secrets.OTTERWISE_TOKEN }}
    file: build/coverage/clover.xml

Step 3: Ensure Proper Git Checkout Depth

For the action 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 to OtterWise
      uses: getOtterWise/github-action@v1
      with:
        token: ${{ secrets.OTTERWISE_TOKEN }}

Common Test Framework Commands

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

Alternative: Using the Bash Uploader

If you prefer not to use the GitHub Action, you can use the bash uploader script instead:

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

The bash 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

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