Improve documentation of 'CI_JOB_TOKEN' variable
As described by me in the discussion at !28059 (comment 313026160), I see two problems with the current description of CI_JOB_TOKEN
variable which currently says:
Token used for authenticating with the GitLab Container Registry and downloading dependent repositories
-
For GitLab Container Registry authorization we have two dedicated variables:
CI_REGISTRY_USER
andCI_REGISTRY_PASSWORD
. True, they currently use the "legacy" values ofci-job-token
as a user and the real token as the password. But this may change in the future. And while currently usingdocker login --user ci-job-token --password $CI_JOB_TOKEN $CI_REGISTRY
will work, it will be broken if we will decide to introduce dedicated credentials for the per-job access to the registry. While the dedicated variables should follow the change.I propose to not suggest usage of this variables to authenticate into the registry and instead explicitly that
For GitLab Container Registry authorization please look on the CI_REGISTRY_USER and CI_REGISTRY_PASSWORD variables
. -
The lack of details. Apart of container registry authentication (which is the legacy usage now) the documentation mentions only
downloading dependent repositories
. And there is definitely more use cases.The variable can be used to trigger other downstream pipelines, to interact with our package registries, to interact with other API endpoints... Way more than just downloading dependent repositories.
I don't think that this token allows access to all our API endpoints, but it definitely allows to use many of them. And in all cases it has specific behavior: it inpersonificates the user who is the "owner" of a job. So for example if I start a pipeline all jobs are connected with my GitLab user as the owner. So in theory with the token passed with
CI_JOB_TOKEN
variable the job script should be able to do multiple things with GitLab just like it would be me personally.Current description doesn't point this possibilities. It also can create a false feeling of "security" for those who would like to do an analysis of how you can access GitLab.
I think that it would be best to link to https://docs.gitlab.com/ee/user/permissions.html#gitlab-cicd-permissions instead of writing this incomplete and partially legacy information. And next to review the CI/CD permissions
documentation to see what should be updated (I think there is way more possibilities now than what this table shows).