Loading
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,
glabresolves the token in order: personal access token (GITLAB_TOKEN/GITLAB_ACCESS_TOKEN/OAUTH_TOKEN) first, thenCI_JOB_TOKEN. - This precedence applies to all API commands, not just
glab auth login. - A
GITLAB_TOKENdefined as a CI/CD variable overrides the job token, even with CI auto-login enabled or afterglab 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
tokenkey: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.GitLabClientininternal/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
- This is initially reported by a customer (internal only zd ref)
- Related MR to clarify in the main gitlab repo: Docs: document token used by the release keyword (gitlab!242374 - merged)
- Related to Docs: Warn about GITLAB_TOKEN CI/CD variable co... (gitlab#604239)
Edited by Marcel Amirault