> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codeant.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions

> Set up GitHub Actions workflow for coverage reporting.

## CodeAnt AI Coverage Upload Action

Upload test coverage reports to CodeAnt AI for comprehensive analysis, visualization, and tracking of your code coverage metrics.

You can find this action on the [GitHub Marketplace](https://github.com/marketplace/actions/codeant-ai-coverage-upload).

### Features

* 📊 Upload coverage reports in XML format (Cobertura XML, JaCoCo XML)
* 🔍 Automatic coverage analysis and insights
* 📈 Track coverage trends over time
* 🎯 Integration with pull requests
* 🚀 Easy setup with minimal configuration

## Usage

### Basic Example

```yaml theme={null}
name: Test Coverage

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

jobs:
  coverage:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run tests with coverage
        run: |
          # Your test command that generates coverage report
          pytest --cov --cov-report=xml

      - name: Upload coverage to CodeAnt AI
        uses: CodeAnt-AI/codeant-coverage-action@v0.0.5
        with:
          access_token: ${{ secrets.ACCESS_TOKEN_GITHUB }}
          coverage_file: coverage.xml
```

### Advanced Example

```yaml theme={null}
- name: Upload coverage to CodeAnt AI
  uses: CodeAnt-AI/codeant-coverage-action@v0.0.5
  with:
    access_token: ${{ secrets.ACCESS_TOKEN_GITHUB }}
    coverage_file: coverage.xml
    api_base: https://api.codeant.ai
    platform: github
    base_url: https://github.com
    module: backend
    module_path: services/backend
```

## Inputs

| Input           | Description                                        | Required | Default                  |
| --------------- | -------------------------------------------------- | -------- | ------------------------ |
| `access_token`  | GitHub Access Token for authentication             | Yes      | -                        |
| `coverage_file` | Path to the coverage XML file (e.g., coverage.xml) | Yes      | `coverage.xml`           |
| `api_base`      | CodeAnt AI API base URL                            | No       | `https://api.codeant.ai` |
| `platform`      | Git platform (github, gitlab, bitbucket)           | No       | `github`                 |
| `base_url`      | Base URL of the git platform                       | No       | `https://github.com`     |
| `module`        | Module name for monorepo setups                    | No       | -                        |
| `module_path`   | Module path for resolving files in monorepo        | No       | -                        |

## Supported Coverage Formats

> **Important:** Only XML format is supported for coverage reports.

* Cobertura XML (.xml)
* JaCoCo XML

## Setup

### 1. Get Your GitHub Access Token

* Log in to your GitHub account
* Go to **Settings** > **Developer settings** > **Personal access tokens** > **Tokens (classic)**
* Click **Generate new token (classic)**
* Select the `repo` scope
* Generate and copy the token

### 2. Generate Coverage Report

First, ensure your test suite generates a coverage report. Here are examples for common languages:

**Python (pytest)**

```bash theme={null}
pytest --cov --cov-report=xml
```

**JavaScript/TypeScript (Jest)**

```bash theme={null}
jest --coverage --coverageReporters=cobertura
```

**Java (Maven)**

```bash theme={null}
mvn test jacoco:report
```

**Go**

```bash theme={null}
go test -coverprofile=coverage.out ./...
gocov convert coverage.out | gocov-xml > coverage.xml
```

### 3. Add Secrets

Add your GitHub Access Token to your repository secrets (after generating it via Settings → Developer settings → Personal access tokens):

1. Go to your repository Settings
2. Navigate to Secrets and variables → Actions
3. Click "New repository secret"
4. Name: `ACCESS_TOKEN_GITHUB`
5. Value: Your GitHub Access Token

### 4. Configure Workflow

Add the action to your GitHub Actions workflow as shown in the usage examples above.

## Token Permissions

The access token requires the following permissions:

* **Metadata**: Read-only access
* **Commit statuses**: Read and write access

<img src="https://mintcdn.com/codeantai/cPAPWnajTUNzakyT/images/integration/test_coverage/github/github_token_permissions.png?fit=max&auto=format&n=cPAPWnajTUNzakyT&q=85&s=53c269fb27d95b8b4a02f1d88a8aa9da" alt="Token permissions" width="848" height="530" data-path="images/integration/test_coverage/github/github_token_permissions.png" />

These permissions allow the token to access repository metadata and update commit status checks for coverage reporting.

## Coverage config file

You have to create a .coveragerc file in the project's root folder to include all the source files in the test coverage calculation.

Example:

```yaml theme={null}
# include every Python file under the repo root
source = .

# exclude tests, virtualenvs, build artifacts, etc.
omit =
    */tests/*
    */.venv/*
    */build/*
    */dist/*
```

When you assign source to "." , It checks for every python file in the root folder and its sub directories. You can omit some directories by placing them in the omit section of the file.

## How it works

With the above configuration:

1. coverage run -m pytest tests/ will count every .py under the workspace as “valid” lines except for those in the omitted directories.
2. Lines actually executed by your tests are marked “covered.”
3. coverage xml -o coverage.xml produces a Cobertura-style report reflecting true coverage over the entire codebase.
4. Using this coverage xml, we calculate the coverage percentage and the status check will be done on every new push to the branch.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/CodeAnt-AI/codeant-coverage-action).