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

# Coverage Tokens

Coverage tokens are used to authenticate when uploading code coverage reports to Qlty. This page explains the different types of tokens available, how to obtain them, and best practices for managing them securely.

## Types of Coverage Tokens

Qlty offers three authentication methods for uploading coverage reports:

### 1. OpenID Connect (OIDC) with GitHub Actions

OIDC is a tokenless approach that uses temporary credentials. It's the most secure method as it doesn't require storing any long-lived tokens.

**Benefits:**

* No token management required
* Enhanced security with short-lived credentials
* Automatic token rotation
* Zero setup beyond the initial configuration

**Limitations:**

* Only works with GitHub Actions
* Requires the `id-token: write` permission in your workflow

### 2. Workspace-level Coverage Tokens

Workspace tokens provide coverage upload access for all repositories within a workspace (GitHub organization or user account).

**Benefits:**

* One token covers all repositories in a workspace
* Simplified setup for organizations with many repositories
* Works with any CI provider

**Limitations:**

* Broader scope than project tokens (less secure)
* Must be rotated manually if compromised

### 3. Project-level Coverage Tokens

Project tokens provide coverage upload access for a single repository.

**Benefits:**

* Most restrictive scope for enhanced security
* Independent token management per repository
* Works with any CI provider

**Limitations:**

* Requires separate token management for each project
* Must be rotated manually if compromised

## Obtaining Coverage Tokens

### Workspace-level Token

1. Sign in to Qlty Cloud
2. Go to Workspace Settings
3. Navigate to the "Code Coverage" tab
4. Copy the workspace coverage token

### Project-level Token

1. Sign in to Qlty Cloud
2. Navigate to your project
3. Go to Project Settings
4. Select the "Code Coverage" tab
5. Copy the project coverage token

## Using Coverage Tokens

### In GitHub Actions

Using OIDC (recommended):

```yaml lines theme={"system"}
- uses: qltysh/qlty-action/coverage@v2
  with:
      oidc: true
      files: coverage/lcov.info
```

Using a coverage token:

```yaml lines theme={"system"}
- uses: qltysh/qlty-action/coverage@v2
  with:
      token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
      files: coverage/lcov.info
```

### In Other CI Systems

Use the token as an environment variable:

```bash lines theme={"system"}
QLTY_COVERAGE_TOKEN=your_token qlty coverage publish coverage/lcov.info
```

## Security Best Practices

### Token Storage

Coverage tokens should be treated as sensitive credentials:

* **Never** commit tokens to your repository
* **Always** use CI/CD environment variables or secrets
* **Don't** expose tokens in build logs
* **Don't** share tokens in communication channels

### Environment Variable Storage

Store your coverage token as a secret environment variable in your CI system:

* **GitHub Actions**: Repository or organization secrets
* **CircleCI**: Environment variables or contexts
* **Travis CI**: Environment variables
* **GitLab CI**: CI/CD variables
* **Azure DevOps**: Pipeline variables
* **Jenkins**: Credentials binding plugin

### Token Rotation

Rotate your coverage tokens periodically or immediately if you suspect they've been compromised:

1. Go to the same place where you obtained the token
2. Click "Refresh Token" (or similar)
3. Update the token in all your CI configurations

Qlty will invalidate the old token and generate a new one.

### Scope Limitation

Use the token with the most limited scope that meets your needs:

* Use OIDC whenever possible with GitHub Actions
* Use project-level tokens when working with a single repository
* Use workspace-level tokens only when managing multiple repositories

## Common Questions

### What can someone do with a coverage token?

Coverage tokens only allow uploading coverage reports to specific projects or workspaces. They cannot:

* Access other Qlty features
* Modify repository settings
* Access source code
* View private data

The main risk of a leaked token is someone uploading fake coverage reports.

### How do I rotate a token?

Tokens can be rotated through the same UI where you obtained them. Click "Refresh Token" to generate a new token and invalidate the old one.

### Can I use multiple tokens?

Yes, you can use different tokens for different contexts. For example:

* Different tokens for production vs. development environments
* Different tokens for different CI pipelines
* Different tokens for manual vs. automated uploads

### Should I verify my tokens are working?

Yes, after setting up a new token, run a test upload to verify it's working correctly:

```bash lines theme={"system"}
QLTY_COVERAGE_TOKEN=your_token qlty coverage publish coverage/lcov.info
```

Then check the project's coverage settings to confirm the report was received.

## Troubleshooting

### Authentication Failures

If you get an authentication error:

* Verify the token is correct (no extra spaces or line breaks)
* Check that the environment variable is correctly defined
* Ensure the token has not been rotated
* Verify you're using the token in the correct context (workspace vs. project)

### Invalid Token Format

If you see "Invalid token format" errors, check that:

* The token is the complete string without any truncation
* There are no extra characters or whitespace
* You're not accidentally using a different type of token

## See Also

* [CI Integration](/coverage/ci) - Set up automated coverage reporting
* [GitHub OIDC](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect) - Detailed guide on using OIDC with GitHub Actions
* [Troubleshooting](/coverage/troubleshooting) - Common issues and solutions