Authentication

Some CLI commands (upload, download, access, list tests) require authentication. Each authentication method also determines what you’re authorized to do.

The CLI resolves credentials in the following priority order:

Priority	Method	Best for	Access scope
1	Access Token	CI providers without OIDC support	Read & upload for one project
2	Device OAuth	Local development	Same as the logged-in user
3	GitHub OIDC	GitHub Actions, with no secrets to manage	Read & upload for one project
4	GitLab OIDC	GitLab CI/CD on gitlab.com, with no secrets to manage	Read & upload for one project

Access Token

Pass a token explicitly via --access-token flag or the FLAKINESS_ACCESS_TOKEN environment variable.

# Via flag
flakiness upload ./flakiness-report --access-token <token>

# Via environment variable
export FLAKINESS_ACCESS_TOKEN=<token>
flakiness upload ./flakiness-report

An access token grants read and upload access to a single project. Use it on CI providers where OIDC is not available: CircleCI, Jenkins, Azure Pipelines, Buildkite, and self-managed GitLab instances.

Tip

You can find your project’s access token in the project settings on Flakiness.io. Each token is scoped to one project and allows reading test data and uploading reports.

Device OAuth

Log in interactively from your terminal. The CLI opens your browser for authorization and stores the session locally.

flakiness auth login

Device OAuth grants the same access as your user account — all projects and organizations you have access to on Flakiness.io.

Sessions are stored in the platform-specific config directory:

• macOS: ~/Library/Application Support/flakiness/config.json
• Linux: ~/.config/flakiness/config.json
• Windows: ~/AppData/Roaming/flakiness/config.json

This is the best option for local development.

GitHub OIDC

When running inside GitHub Actions with id-token: write permission, the CLI requests an OIDC token from GitHub and exchanges it for a Flakiness access token. There are no secrets to create or rotate.

permissions:
  id-token: write

steps:
  - run: flakiness upload ./flakiness-report --project myorg/myproject

--project (or FLAKINESS_PROJECT) is required for OIDC authentication. Like an access token, GitHub OIDC grants read and upload access to the specified project.

Tip

GitHub OIDC is the recommended method for GitHub Actions — no secrets to create or rotate. See the GitHub Actions guide for full setup instructions.

GitLab OIDC

GitLab mints an ID token when the job starts and exposes it as an environment variable. Declare one named FLAKINESS_ID_TOKEN in .gitlab-ci.yml and the CLI uses it to authenticate:

test:
  id_tokens:
    FLAKINESS_ID_TOKEN:
      aud: myorg/myproject
  script:
    - flakiness upload ./flakiness-report --project myorg/myproject

The aud claim is fixed when the token is minted, so it must name the same project you pass to --project. The CLI rejects a mismatched token before contacting Flakiness.io. On GitLab 16.1 and later aud expands CI/CD variables, so a shared pipeline template can use aud: $FLAKINESS_PROJECT.

Like an access token, GitLab OIDC grants read and upload access to the specified project.

gitlab.com only

Flakiness.io verifies GitLab ID tokens against https://gitlab.com. Pipelines running on a self-managed GitLab instance must use an access token instead.

Your Flakiness.io project must be linked to the GitLab project running the pipeline. Flakiness.io checks the token’s project_path claim against that link and rejects the upload when they differ.

Auth Commands

auth login

Log in to Flakiness.io via Device OAuth. Opens your browser for authorization.

flakiness auth login

Options:

• -e, --endpoint <url> — Service endpoint (default: https://flakiness.io, env: FLAKINESS_ENDPOINT)

auth logout

Log out from the current session.

flakiness auth logout

auth status

Show the currently logged-in user. Exits with code 1 if not logged in.

flakiness auth status

Note

flakiness auth whoami is an alias for auth status and continues to work.