GitLab MCP với Gemini CLI

Gemini CLI là coding agent CLI chính thức của Google, dùng model Gemini và hỗ trợ MCP (Model Context Protocol) từ khá sớm. Với engineer đã có sẵn Google Workspace/Google Cloud trong hệ thống công ty, hoặc muốn tận dụng context window rất lớn của Gemini để xử lý MR/pipeline log dài, Gemini CLI kết hợp GitLab MCP là một lựa chọn đáng cân nhắc bên cạnh Claude Code. Bài này hướng dẫn cài đặt, các lệnh quản lý project/pipeline thực tế, một ví dụ theo dõi CI/CD, và so sánh hành vi tool-calling giữa Gemini CLI với Claude Code để bạn chọn đúng công cụ cho từng tình huống.

Cài Đặt và Kết Nối GitLab MCP Với Gemini CLI

Gemini CLI đọc cấu hình MCP từ file ~/.gemini/settings.json (global) hoặc .gemini/settings.json ở root project (ưu tiên cao hơn, phù hợp để commit vào repo cho team dùng chung). Khai báo GitLab MCP server dưới key mcpServers:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "$GITLAB_PERSONAL_ACCESS_TOKEN",
        "GITLAB_API_URL": "https://gitlab.your-company.com/api/v4"
      },
      "timeout": 30000
    }
  }
}

Cấu trúc này gần giống Claude Code, nhưng có vài điểm riêng của Gemini CLI:

• Trường timeout (đơn vị milliseconds) kiểm soát thời gian chờ tối đa cho mỗi tool call — nên tăng lên (ví dụ 60000) nếu GitLab self-hosted của công ty có latency cao hoặc network qua VPN.
• Gemini CLI hỗ trợ inject biến môi trường bằng cú pháp $VAR_NAME trực tiếp trong string, không cần dấu ngoặc nhọn như Claude Code.
• Ngoài mcpServers trong settings.json, Gemini CLI còn cho đăng ký nhanh qua lệnh:

gemini mcp add gitlab -- npx -y @zereight/mcp-gitlab

sau đó set biến môi trường qua shell trước khi chạy gemini, thay vì hard-code trong file.

Xác nhận kết nối bằng lệnh trong session:

gemini
/mcp list

Kết quả sẽ hiện gitlab kèm số lượng tool đã discover được (thường 20-30 tool tùy version của @zereight/mcp-gitlab). Nếu số tool hiện là 0, thường do server khởi động subprocess thất bại — chạy thử npx -y @zereight/mcp-gitlab trực tiếp ngoài Gemini CLI để xem log lỗi gốc.

Mẹo: Gemini CLI có context window rất lớn (thường 1 triệu token với bản Gemini 2.5 Pro) — điều này nghĩa là bạn có thể an tâm hơn khi yêu cầu agent load nhiều pipeline log hoặc nhiều MR diff cùng lúc so với model có context nhỏ hơn, nhưng vẫn nên giới hạn phạm vi trong prompt để tránh tốn cost và thời gian phản hồi không cần thiết.

Quản Lý Project và Pipeline GitLab Từ Gemini CLI

Gemini CLI mạnh ở việc xử lý dữ liệu dài (pipeline log, danh sách project lớn) nhờ context window rộng. Vài prompt thực tế phù hợp với thế mạnh này:

Liệt kê toàn bộ project trong một group và trạng thái pipeline gần nhất:

List all projects under GitLab group company/backend. For each project, get the latest pipeline on the default branch and show its status (success/failed/running).

Tìm project có pipeline fail liên tục:

Across all projects in group company/backend, find any project whose last 3 pipelines on main branch all failed. List them with the failure reason of the most recent one.

Tổng hợp báo cáo release cuối tuần:

Get all merge requests merged into main in project company/backend/payment-service this week (from Monday to today). Summarize them into a release note in Vietnamese, grouped by label (feature, bug-fix, chore).

Với prompt dạng "quét nhiều project" như trên, Gemini CLI thường xử lý tốt hơn các CLI agent có context nhỏ vì nó giữ được toàn bộ kết quả trung gian (danh sách project, pipeline status từng cái) trong cùng một lượt reasoning mà không cần tóm tắt sớm để tránh tràn context.

Mẹo: Với prompt quét nhiều project cùng lúc, luôn giới hạn rõ group/subgroup cụ thể trong câu lệnh — đừng để agent tự gọi list_projects không filter, vì với công ty có hàng trăm project, việc này vừa chậm vừa dễ vượt rate limit GitLab API giữa chừng.

Ví Dụ Thực Tế: Theo Dõi Trạng Thái Pipeline CI/CD Với Gemini CLI và GitLab MCP

Đi qua kịch bản thường gặp: pipeline vừa fail sau khi merge, bạn cần agent giúp xác định nguyên nhân nhanh trước khi tự đọc log dài dòng.

Bước 1 — Lấy trạng thái pipeline mới nhất:

Get the latest pipeline for project company/backend/payment-service on branch main. Show overall status and list all jobs with their individual status.

Bước 2 — Đào sâu vào job fail:

The job "run-integration-tests" failed. Fetch its full log, find the actual error (not just the generic "job failed" message), and explain in plain English what broke.

Đây là chỗ context window lớn của Gemini phát huy tác dụng rõ nhất — log của integration test suite có thể dài hàng nghìn dòng với rất nhiều noise (log setup, log teardown), nhưng Gemini CLI vẫn giữ được toàn bộ log trong context để lọc ra đúng dòng lỗi thật, thay vì bị agent tóm tắt nhầm do phải cắt bớt log giữa đường.

Bước 3 — Yêu cầu đề xuất fix và tạo issue theo dõi:

Based on the error you found, suggest a likely root cause and a fix approach. Then create a GitLab issue in the same project titled with the error summary, put your analysis in the description, assign label "ci-failure", and link it to the pipeline URL.

Bước 4 — Theo dõi lại sau khi fix được push:

I just pushed a fix to branch fix/integration-test-flaky. Trigger a new pipeline for this branch if it hasn't started automatically, then wait and report back the status of job "run-integration-tests" once it completes.

Lưu ý: khả năng "wait và poll" phụ thuộc vào việc GitLab MCP server có tool polling hay không — nếu server chỉ hỗ trợ tool get_pipeline một lần (không tự lặp), bạn cần yêu cầu agent gọi lại theo chu kỳ (ví dụ "check again every prompt turn until status is not running") hoặc tự chạy lại lệnh sau vài phút.

Mẹo: Khi debug pipeline fail phức tạp nhiều job liên đới, yêu cầu agent liệt kê toàn bộ dependency graph giữa job (needs: trong .gitlab-ci.yml) trước khi phân tích — tránh trường hợp agent chẩn đoán nhầm job B là nguyên nhân trong khi job B fail chỉ vì job A (mà nó phụ thuộc) đã fail trước đó.

So Sánh Hành Vi GitLab MCP Giữa Gemini CLI và Claude Code

Cùng một GitLab MCP server (@zereight/mcp-gitlab), nhưng hành vi tool-calling giữa hai agent CLI có khác biệt đáng kể trong thực tế sử dụng:

Trong thực tế, nhiều team dùng cả hai theo tình huống: Gemini CLI cho các task cần "đọc nhiều, tổng hợp nhiều" (report cuối tuần, quét nhiều project, phân tích log dài), còn Claude Code cho các task cần độ chính xác cao ở hành động ghi (tạo MR, merge, review code) nhờ khả năng bám sát instruction nhiều bước tốt hơn.

Mẹo: Đừng chọn agent CLI dựa theo "thích cái nào hơn" một cách cảm tính — thử cùng một prompt phức tạp (ví dụ luồng review MR 4-5 bước) trên cả hai công cụ với project thật của bạn, ghi lại agent nào bỏ sót bước hoặc gọi sai tool nhiều hơn, rồi quyết định dựa trên dữ liệu thực tế của chính team bạn.

Mẹo Thực Chiến

Một số kinh nghiệm khi vận hành GitLab MCP với Gemini CLI trong công việc hàng ngày:

• Với các câu lệnh quét nhiều project/pipeline, luôn set timeout trong mcpServers cao hơn mức default — pipeline log lớn cần thời gian fetch lâu hơn so với các API call đơn giản như get_merge_request.
• Gemini CLI hỗ trợ chọn model theo lệnh (gemini --model gemini-2.5-flash cho task nhanh, gemini --model gemini-2.5-pro cho reasoning sâu) — dùng Flash cho các task đơn giản như "list pipeline status" để tiết kiệm cost, chỉ chuyển qua Pro khi cần agent tự phân tích log/đề xuất fix.
• Lưu prompt template hay dùng (ví dụ "weekly release note" ở trên) vào file riêng và dùng lệnh gemini -p "$(cat prompts/weekly-release.txt)" để tái sử dụng mà không cần gõ lại mỗi tuần.

Mẹo: Nếu công ty có GitLab self-hosted với domain nội bộ (VPN-only), luôn test kết nối GitLab MCP server ngay trong mạng công ty trước khi troubleshoot ở tầng agent — rất nhiều lỗi "MCP server not responding" thực chất chỉ là do máy chưa vào VPN, không liên quan gì tới cấu hình Gemini CLI.