結論先說
- Claude Code 在 GitLab 流水線裏底層靠無頭模式(
claude -p)驅動:無需任何特殊商業網關,只要 Runner 容器能訪問 Anthropic 接口(或企業 Bedrock / Vertex 網關)就能跑。 - 密鑰必須配置在 GitLab 的 CI/CD Variables 並勾選掩碼(Masked):注意不要盲目勾選「僅受保護分支(Protected)」,否則普通功能分支提上來的 Merge Request 拿不到變量會直接報未授權。
- 容器裏最常踩的坑是漏加
PATH:官方原生安裝腳本把可執行文件放在~/.local/bin,在輕量容器before_script裏必須顯式把它導出進PATH。 - 安全第一原則:自動審 MR 的作業只開放只讀工具與評論接口,去掉
Edit和Write,防止提示詞注入篡改流水線源碼。

圖:本站根據 Claude Code 官方文檔 GitLab CI/CD 整理的示意圖
本文根據 Claude Code 官方文檔《Claude Code GitLab CI/CD》與《Run Claude Code programmatically》整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 或 GitLab 官方網站。
適用於誰
- 搜「claude code gitlab ci」「gitlab merge request 自動代碼審查 claude」的研發與運維工程師;
- 公司代碼託管在 GitLab(含極狐或內網自建實例),沒法直接套用 GitHub Actions 現成插件(見 /guides/claude-code-github-actions),需要手寫
.gitlab-ci.yml跑自動化審查或修補的人; - 在容器流水線裏裝完 Claude Code 後一直報
claude: not found或 401 讀不到密鑰的人。
一、第一步:在 GitLab 項目後台配好安全憑證
CI 容器沒有人工交互介面,不能走個人網頁訂閱登入,必須走開發者密鑰或雲平台憑證(認證差異見 /guides/claude-code-use-api-key-instead-of-login):
- 打開目標 GitLab 倉庫,依次進入 設定(Settings) → CI/CD → 變量(Variables);
- 新增變量
ANTHROPIC_API_KEY,填入在控制檯創建的專用流水線密鑰,勾選 掩碼變量(Mask variable) 防止密鑰打印進構建日誌; - 如果需要讓作業把審查意見自動回寫到當前 Merge Request 評論區,再創建一個最小範圍(
api或只讀加討論權限)的項目訪問令牌(Project Access Token),存為GITLAB_TOKEN。
二、第二步:編寫 .gitlab-ci.yml 只讀審查模板
下面是一個在每次提交或更新 Merge Request 時自動對比目標分支改動、調用 glab(或內部接口)發表審查摘要的標準作業模板(無頭參數細節見 /guides/claude-code-headless-mode):
yaml
stages:
- ai-review
claude_mr_review:
stage: ai-review
image: node:22-bookworm-slim
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
variables:
GIT_DEPTH: 0
before_script:
- apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates
- curl -fsSL https://claude.ai/install.sh | bash
- export PATH="$HOME/.local/bin:$PATH"
script:
- git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
- >
claude -p "對比 origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD 的代碼變更,
只指出會導致線上故障、越權漏洞或缺失邊界處理的實質缺陷,跳過純代碼風格建議,輸出簡潔 Markdown。"
--allowedTools "Read,Grep,Glob,Bash(git diff *),Bash(git log *)"
--max-turns 8 > review_report.md
- cat review_report.md
artifacts:
paths:
- review_report.md
expire_in: 7 days
看清模板裏的三處關鍵防護設計:
GIT_DEPTH: 0確保容器拉取完整分支引用,避免git diff找不到目標基準分支提交;--allowedTools嚴格把Bash收窄到只允許執行git diff和git log,不給任意命令執行權,也沒有放行Edit與Write;--max-turns 8封死單次作業最大工具循環輪數,避免遇到超大變更集把整個月 API 預算跑穿。拿到review_report.md後,只需加一行調用 GitLab Notes API 或glab mr note即可把報告貼回 MR 頁面(團隊審查分工規範見 /guides/claude-code-team-code-review-workflow)。

圖:本站根據 Claude Code 官方文檔 GitLab CI/CD 整理的示意圖
三、需要讓流水線「自動改代碼提交」時怎麼放權
除了只讀審查,官方 GitLab 文檔也支持「手動在網頁觸發流水線並傳入修改指令(如修單測、補類型註解)」的寫入模式。若要啟用自動改碼,請務必把寫入作業和自動觸發的公開 MR 作業分開:
- 將觸發條件限制為
$CI_PIPELINE_SOURCE == "web"(僅限倉庫內部有權限的研發人員手動點運行並傳入需求變量),不要對外部未知派生倉庫自動開放寫權限; - 在該受控作業裏加上
--permission-mode acceptEdits並放行Edit、Write與受限測試命令,改完跑綠單測後再由腳本創建獨立修補分支供人工合併。
平時成員在本地終端先用自己的 Claude Code 預審改完再推 GitLab,能大幅減少 CI 流水線反覆重跑的開銷;個人本地研發環境的官方訂閱方案可參考 /chongzhi/claude-code。
常見問題
Q:每次起流水線都重新 curl 下載安裝一遍太慢怎麼辦?
生產團隊強烈建議基於內部基礎鏡像預先把 Claude Code、git 和 glab 打進自定義 Runner 鏡像推到內網鏡像倉庫(Harbor / GitLab Container Registry),流水線啟動直接秒進 script 階段,還能徹底避免外網下載波動導致構建偶發失敗。
Q:企業合規要求走 AWS Bedrock 或 Google Vertex AI 怎麼改配置?
按官方文檔,在 GitLab CI/CD Variables 裏配置 CLAUDE_CODE_USE_BEDROCK=1(或 CLAUDE_CODE_USE_VERTEX=1)並配合 GitLab OIDC 身份聯合換取臨時雲憑證即可,連長期靜態 ANTHROPIC_API_KEY 都不用存。
Q:怎麼讓流水線審查遵守我們團隊自己的業務規範?
不需要把幾千字規範全塞進 .gitlab-ci.yml 的 -p 命令字符串裏。只要你的倉庫根目錄已經提交了團隊共享的 CLAUDE.md 和 .claude/rules/ 規則文件,無頭運行的 claude -p 啟動時會自動讀取倉庫上下文,按同一把尺子檢查每次提交。
相關教學
- /guides/claude-code-github-actions:Claude Code 在 GitHub Actions 中的配置對比
- /guides/claude-code-headless-mode:
claude -p非交互模式參數與腳本自動化詳解 - /guides/claude-code-team-code-review-workflow:團隊雙層代碼審查工作流設計
- /guides/claude-code-use-api-key-instead-of-login:Claude Code 配置 API Key 與雲平台認證
參考資料
- Claude Code 官方文檔:Claude Code GitLab CI/CD — https://code.claude.com/docs/en/gitlab-ci-cd
- Claude Code 官方文檔:Run Claude Code programmatically — https://code.claude.com/docs/en/headless
0 條評論
還沒有評論,來搶沙發~