docs: clarify token precedence for CI job token authentication

What does this MR do?

Documents the token resolution precedence used by glab so that users of the GitLab release keyword (and any CI job) understand which token is actually used to authenticate.

Adds a Token precedence subsection to the CI Job Token section of the README, stating:

  • For every authenticated command, glab resolves the token in order: personal access token (GITLAB_TOKEN / GITLAB_ACCESS_TOKEN / OAUTH_TOKEN) first, then CI_JOB_TOKEN.
  • This precedence applies to all API commands, not just glab auth login.
  • A GITLAB_TOKEN defined as a CI/CD variable overrides the job token, even with CI auto-login enabled or after glab auth login --job-token.

Also add details about GITLAB_ACCESS_TOKEN & OAUTH_TOKEN under "GitLab access variables" table

Why

The only place this precedence was previously documented was in the GLAB_ENABLE_CI_AUTOLOGIN help text, scoped to auto-login. Users hitting the release keyword had no clear reference.

Where the behavior comes from

  • Token selection switch (PAT before job token): internal/api/client.go (NewClientFromConfig).
  • Env var mapping for the token key: internal/config/schema.go.
  • Confirmed by the "CI auto-login PAT takes precedence over job token" test in internal/api/client_test.go.
  • The same builder is used by all commands through Factory.ApiClient / Factory.GitLabClient in internal/cmdutils/factory.go.

Notes

README.md is hand-maintained (not generated by make gen-docs), so it is edited directly. No command source changed, so no doc regeneration is required.

REF

Edited by Marcel Amirault

Merge request reports

Loading
Loading