Claude Code 接入 GitLab CI/CD 教學:.gitlab-ci.yml 配置與自動審查 Merge Request

很多企業內網或自託管倉庫用的是 GitLab 而不是 GitHub。本文根據 Claude Code 官方 GitLab CI/CD 文檔,講清 CI 變量掩碼配置、.gitlab-ci.yml 作業模板、PATH 路徑避坑以及只讀審查 Merge Request 的最小權限寫法。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 其他 帳號

結論先說

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

Claude Code 接入 GitLab CI 四步

圖:本站根據 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):

  1. 打開目標 GitLab 倉庫,依次進入 設定(Settings) → CI/CD → 變量(Variables);
  2. 新增變量 ANTHROPIC_API_KEY,填入在控制檯創建的專用流水線密鑰,勾選 掩碼變量(Mask variable) 防止密鑰打印進構建日誌;
  3. 如果需要讓作業把審查意見自動回寫到當前 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)。

GitLab 流水線常見報錯與權限排查

圖:本站根據 Claude Code 官方文檔 GitLab CI/CD 整理的示意圖

三、需要讓流水線「自動改代碼提交」時怎麼放權

除了只讀審查,官方 GitLab 文檔也支持「手動在網頁觸發流水線並傳入修改指令(如修單測、補類型註解)」的寫入模式。若要啟用自動改碼,請務必把寫入作業和自動觸發的公開 MR 作業分開:

  1. 將觸發條件限制為 $CI_PIPELINE_SOURCE == "web"(僅限倉庫內部有權限的研發人員手動點運行並傳入需求變量),不要對外部未知派生倉庫自動開放寫權限;
  2. 在該受控作業裏加上 --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 啟動時會自動讀取倉庫上下文,按同一把尺子檢查每次提交。

相關教學

參考資料

  • 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

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  5. 05

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  6. 06

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  4. 04

    LangGraph 怎麼使用 MCP:用 langchain-mcp-adapters 接入本地與遠程工具

    想讓自建的 LangGraph 狀態圖直接調用現成的 MCP 伺服器,官方標準方案是安裝 langchain-mcp-adapters 並使用 MultiServerMCPClient。本文講清 stdio 與 streamable_http 兩種配置寫法、異步圖運行及按節點分工具技巧。

    Claude其他 AI 工具0
  5. 05

    LangGraph 入門教學:Python 安裝、核心概念與跑通第一個狀態圖智能體

    面向搜「python 安裝 langgraph」和「langgraph 中文 文檔」的初學者:本文按 LangChain 官方最新 Graph API 規範,講清安裝步驟、State/Node/Edge 四大概念,並從零寫出第一個帶工具調用循環的 StateGraph。

    Claude其他 AI 工具0
  6. 06

    Claude Agent SDK 子代理怎麼寫:AgentDefinition 配置、權限收斂與 Python/TS 示例

    在 Python 或 TypeScript 裏用 Claude Agent SDK 編排多角色協作,核心是配置 ClaudeAgentOptions 的 agents 字段與 AgentDefinition。本文講清必開的 Agent 委派權限、工具收斂、模型分級與完整代碼示例。

    Claude0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~