私有GitLab实例流水线认证失败，需配置何种令牌？

问题描述 #

在私有GitLab实例https://gitlab.example.com运行流水线时，任务因认证失败终止，报错信息如下：

remote: HTTP Basic: Access denied
fatal: Authentication failed for 'http://gitlab.example.com/project/front.git/'

当前使用的.gitlab-ci.yml配置：

stages:
  - test

test-job:
  stage: test
  rules:
    - if: '$CI_COMMIT_BRANCH == "test"'
      when: always
      allow_failure: false
  image: docker:stable
  services:
    - docker:18.09.7-dind
  variables:
    IMAGE_TAG: $CI_COMMIT_BRANCH-$CI_COMMIT_SHORT_SHA
    DOCKER_DRIVER: overlay2
    DOCKER_TLS_CERTDIR: ""
    DOCKER_HOST: tcp://localhost:2375
  before_script:
    - echo "$CI_REGISTRY_USER"
    - docker info
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_JOB_TOKEN" $CI_REGISTRY
  script:
    - echo "Hello, $GITLAB_USER_LOGIN!"
  tags:
    - test

排查与解决步骤 #

1. 定位问题根源 #

报错指向代码仓库拉取认证失败，并非before_script中的Docker登录操作（CI_JOB_TOKEN默认会自动注入并具备Docker registry访问权限）。

2. 检查流水线权限配置 #

• 确认项目设置→CI/CD→流水线中，已启用流水线功能。
• 若test分支是受保护分支，前往项目设置→仓库→受保护分支，确保运行流水线的账户（或流水线服务身份）拥有该分支的读取权限。

3. 验证CI_JOB_TOKEN仓库访问权限 #

前往项目设置→CI/CD→流水线令牌，确认已勾选"允许流水线令牌访问仓库"选项。CI_JOB_TOKEN默认具备拉取当前仓库代码的权限，若该选项关闭会导致拉取失败。

4. 修正仓库地址协议 #

报错中使用http://协议，但你的GitLab实例为https://，可能存在地址不一致问题：

• 检查项目本地远程仓库地址是否为正确的HTTPS地址；
• 可在流水线变量中添加GIT_CLONE_URL，指定为https://gitlab.example.com/project/front.git强制使用HTTPS拉取。

5. 检查Runner配置 #

若使用自行部署的GitLab Runner：

• 确认Runner注册时使用的令牌有效（可在项目设置→CI/CD→Runner中查看）；
• 确保Runner所在分组具备该项目的访问权限，或项目已启用共享Runner。

6. 手动认证测试（可选） #

若以上步骤无效，可在script中临时添加测试命令（测试后删除），验证令牌有效性：

script:
  - git clone https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.example.com/project/front.git
  - echo "Hello, $GITLAB_USER_LOGIN!"

内容的提问来源于stack exchange，提问作者Haru