GitLab CI编译LaTeX并推送PDF至仓库时认证失败求助

以下是针对你遇到的认证失败问题的排查步骤和解决方案：

1. 优先使用GitLab内置的CI_JOB_TOKEN（最省心） #

GitLab CI自动生成的CI_JOB_TOKEN默认拥有当前项目的仓库写入权限，无需手动创建任何token。直接在CI脚本中用它配置git远程地址：

git remote set-url origin https://gitlab-ci-token:$CI_JOB_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git

这个方法能避免手动管理token的权限、过期等问题，优先尝试。

2. 检查自定义token的权限（若坚持用手动创建的token） #

不管是Personal/Project/Deploy Token，必须确保权限达标：

• Personal Access Token：勾选write_repository权限，且该用户对项目拥有开发者及以上权限
• Project Access Token：勾选Repository > Write权限，角色选择Developer或更高等级
• Deploy Token：勾选Repository > Write权限，注意Deploy Token有专属用户名（格式类似gitlab+deploy-token-12345），推送时要将这个用户名填在URL的<TOKEN_NAME>位置

3. 修正CI脚本中的git配置 #

推送前必须完成以下配置，否则会因身份缺失被拒绝：

# 设置git提交身份
git config --global user.name "GitLab CI Runner"
git config --global user.email "ci-runner@your-domain.com"

# 替换远程地址为带认证的格式（以Project Access Token为例）
git remote set-url origin https://<TOKEN_USERNAME>:$PROJECT_ACCESS_TOKEN@gitlab.com/your-namespace/your-project.git

注意：token要存在项目的CI/CD变量中，不要明文写在配置里，变量需勾选Masked避免泄露。

4. 避免CI循环触发 #

提交消息里要加[skip ci]，否则推送后会再次触发CI，形成无限循环：

git commit -m "Auto-update compiled PDF [skip ci]"

5. 排查常见错误点 #

• 检查token是否过期：尤其是Deploy/Project Token，创建时默认可能设置了过期时间，去项目设置里确认
• 检查分支是否为保护分支：如果推送的是保护分支，要确保token对应的用户/runner有推送保护分支的权限（在项目Settings > Repository > Protected branches中配置）
• 确认远程地址拼写正确：不要写错项目路径、GitLab域名，比如把gitlab.com写成gitlab.cn

示例完整.gitlab-ci.yml配置 #

compile-and-push-pdf:
  image: texlive/texlive:latest  # 选用合适的LaTeX镜像
  script:
    - # 编译LaTeX文件，根据论文结构调整命令
    - pdflatex -interaction=nonstopmode paper.tex
    - bibtex paper
    - pdflatex -interaction=nonstopmode paper.tex
    - pdflatex -interaction=nonstopmode paper.tex
    - # 配置git身份
    - git config --global user.name "CI Auto-Builder"
    - git config --global user.email "ci@example.com"
    - # 用内置CI_JOB_TOKEN配置认证
    - git remote set-url origin https://gitlab-ci-token:$CI_JOB_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git
    - # 提交并推送PDF，无变更时跳过提交
    - git add paper.pdf
    - git commit -m "Update compiled PDF from CI [skip ci]" || echo "No changes to PDF, skipping commit"
    - git push origin HEAD:$CI_COMMIT_BRANCH
  only:
    - main  # 仅在主分支触发，可按需调整

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