Authentication

Fromager automatically authenticates to GitHub and GitLab APIs using credentials from netrc or environment variables. Credentials are resolved lazily on the first request to each host.

Authentication is recommended to avoid API rate limits (especially for GitHub) and required to access private repositories or registries.

Credential lookup order

For each host, fromager checks the following sources in order and uses the first match:

GitHub (GITHUB_API_URL, default https://api.github.com):

  1. netrc entry for the host – the password is used as the token

  2. GITHUB_TOKEN environment variable

GitLab (CI_SERVER_URL, default https://gitlab.com):

  1. netrc entry for the host – if the login is gitlab-ci-token a CI job token header is used, otherwise a private token header

  2. CI_JOB_TOKEN environment variable

  3. GITLAB_PRIVATE_TOKEN environment variable

netrc

The requests library, pip, and git all read credentials from ~/.netrc. Another location can be specified by setting the NETRC environment variable. Note that git uses libcurl for HTTPS transport and libcurl only supports the NETRC variable since 8.16.0 (2025-09-10). Older versions only read $HOME/.netrc.

For example, to authenticate to a GitLab package registry with a personal access token:

machine gitlab.com login pat password $token

To authenticate to the GitHub API with a personal access token:

machine api.github.com login pat password $token

Environment variables

To authenticate via environment variables instead of netrc:

# GitHub personal access token (avoids API rate limits)
export GITHUB_TOKEN=<access_token>

# GitLab CI job token (set automatically in CI pipelines)
export CI_JOB_TOKEN=<job_token>

# GitLab personal/project access token
export GITLAB_PRIVATE_TOKEN=<access_token>