Concepts

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):

1- uses: qltysh/qlty-action/coverage@v1
2  with:
3    oidc: true
4    files: coverage/lcov.info

Using a coverage token:

1- uses: qltysh/qlty-action/coverage@v1
2  with:
3    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
4    files: coverage/lcov.info

In Other CI Systems

Use the token as an environment variable:

$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:

$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