·

GitLab MCP với OpenCode

Cài đặt GitLab MCP trong OpenCode để AI agent có thể quản lý repository, merge request và pipeline CI/CD ngay trong trình soạn thảo.

OpenCode là một coding agent CLI mã nguồn mở, chạy được với nhiều LLM provider khác nhau (Anthropic, OpenAI, local model qua Ollama...) và có hệ sinh thái MCP client tương đối trưởng thành. Nếu team bạn không muốn lock-in vào một provider cụ thể, hoặc cần một agent CLI mở để tự host/tự customize, OpenCode kết hợp với GitLab MCP (giao thức kết nối AI agent với công cụ ngoài — Model Context Protocol) cho phép bạn thao tác merge request, issue, pipeline GitLab ngay từ terminal, tương tự Claude Code nhưng không ràng buộc vào một model duy nhất. Bài này hướng dẫn cài đặt, các pattern quản lý MR/issue thực tế, một ví dụ end-to-end, và những hạn chế cần lưu ý khi dùng GitLab MCP trong OpenCode.

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

OpenCode đọc cấu hình MCP server từ file opencode.json ở root project (hoặc ~/.config/opencode/opencode.json cho cấu hình global áp dụng mọi project). Khai báo GitLab MCP server dưới key mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gitlab": {
      "type": "local",
      "command": ["npx", "-y", "@zereight/mcp-gitlab"],
      "environment": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "{env:GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "https://gitlab.your-company.com/api/v4"
      },
      "enabled": true
    }
  }
}

Vài điểm khác biệt so với Claude Code đáng chú ý:

  • OpenCode dùng cú pháp {env:VAR_NAME} để inject biến môi trường vào config, thay vì ${VAR_NAME}. Nhầm cú pháp này là lỗi phổ biến nhất khi mới chuyển từ Claude Code sang OpenCode.
  • type: "local" chỉ định server chạy như subprocess local (qua npx). OpenCode cũng hỗ trợ type: "remote" nếu công ty bạn host GitLab MCP server dưới dạng HTTP endpoint dùng chung cho cả team — tránh mỗi máy phải tự npx download package.
  • Trường enabled cho phép bạn tạm tắt một MCP server mà không cần xóa cấu hình — hữu ích khi debug xem lỗi có phải do GitLab MCP gây ra hay không.

Sau khi lưu file, khởi động OpenCode trong project và chạy lệnh kiểm tra:

opencode
/mcp

Lệnh /mcp trong session sẽ list các MCP server đã đăng ký kèm trạng thái kết nối. Nếu gitlab hiện "error", nguyên nhân thường gặp nhất là token access chưa đủ scope (api, read_api) hoặc biến môi trường GITLAB_PERSONAL_ACCESS_TOKEN chưa được export ở shell trước khi mở OpenCode.

Mẹo: Nếu bạn dùng type: "remote" để share MCP server cho cả team qua HTTP, luôn đặt server đó sau một reverse proxy có auth riêng (ví dụ Basic Auth hoặc mTLS) — đừng để endpoint MCP public hoàn toàn ra internet dù token GitLab đã inject sẵn ở phía server, vì bất kỳ ai gọi được endpoint cũng coi như có quyền hành động thay bạn trên GitLab.

Quản Lý Merge Request và Issue Từ OpenCode

Khi GitLab MCP đã kết nối, bạn ra lệnh bằng ngôn ngữ tự nhiên ngay trong session OpenCode. Model sẽ tự chọn tool tương ứng (list_merge_requests, create_issue, get_merge_request_diffs...) dựa theo intent trong prompt.

Vài prompt thực tế đã dùng tốt trong công việc hàng ngày:

Rà soát MR đang chờ mình review:

List merge requests in project company/backend/payment-service where I'm a reviewer and the MR is still open. For each one, show title, MR IID, author, and how many days it has been open.

Tạo issue từ log lỗi:

I'm pasting a stack trace below. Create a GitLab issue in project company/backend/payment-service titled based on the root exception, put the full stack trace in the description formatted as a code block, and add label "bug" and "needs-triage".

[paste stack trace here]

Đóng issue trùng lặp và liên kết:

Issue #310 in project company/backend/payment-service looks like a duplicate of issue #298. Compare both descriptions to confirm, then if it's really a duplicate, close #310 with a comment linking to #298.

OpenCode hiển thị mỗi tool call kèm diff/preview trước khi thực thi action có ghi dữ liệu (write action), tương tự Claude Code, nhưng UI hiển thị dạng inline trong terminal thay vì panel riêng. Bạn có thể approve từng lệnh, hoặc cấu hình permission mặc định trong opencode.json qua key permission:

{
  "permission": {
    "mcp": {
      "gitlab_list_*": "allow",
      "gitlab_get_*": "allow",
      "gitlab_create_*": "ask",
      "gitlab_merge_merge_request": "deny"
    }
  }
}

Pattern glob gitlab_list_* / gitlab_get_* cho phép bạn allow nhanh toàn bộ tool chỉ-đọc (read-only) mà không cần list tên tool cụ thể từng cái — tiết kiệm công maintain khi GitLab MCP server thêm tool mới.

Mẹo: Đặt gitlab_merge_merge_request ở deny cứng trong config commit vào repo, không chỉ ở máy cá nhân — đảm bảo mọi dev trong team, kể cả người mới join, không thể vô tình để agent tự merge MR vào nhánh chính production.

Ví Dụ Thực Tế: Tạo và Review MR Trong OpenCode

Đi qua một luồng công việc hoàn chỉnh: bạn vừa fix một bug nhỏ ở local, muốn OpenCode giúp tạo MR và tự review trước khi gửi cho đồng nghiệp.

Bước 1 — Yêu cầu tạo MR dựa trên diff local:

Run `git diff main...HEAD` locally to see what I changed. Then create a merge request in project company/backend/payment-service from the current branch into main. Write the MR description in English with sections "## What", "## Why", "## How to test" based on the actual diff content. Add label "bug-fix".

OpenCode sẽ gọi tool local (đọc git diff qua shell) trước, sau đó gọi create_merge_request của GitLab MCP với description đã sinh. Đây là điểm mạnh của OpenCode — nó kết hợp tool hệ thống (shell, file read) và MCP tool trong cùng một reasoning loop mà không cần bạn tách prompt ra nhiều bước.

Bước 2 — Tự review lại MR vừa tạo:

Now fetch the diff of the merge request you just created and review it as a senior engineer. Point out any missing edge case handling, and check if there's a corresponding test file that covers the fix. Post your review as a comment on the MR.

Prompt này khiến agent đóng vai reviewer thật — nó gọi get_merge_request_diffs, đối chiếu với logic thay đổi, và nếu phát hiện thiếu test, sẽ nêu rõ trong comment thay vì chỉ khen chung chung. Chất lượng review phụ thuộc nhiều vào model bạn cấu hình cho OpenCode (ví dụ Claude Sonnet cho reasoning sâu hơn so với model nhỏ hơn).

Bước 3 — Yêu cầu report tóm tắt trước khi gửi Slack:

Summarize the MR (title, what changed, testing done) in 3 bullet points suitable for pasting into a Slack channel, in Vietnamese.

Vì bước này không đụng tool GitLab, agent chỉ tổng hợp lại context đã có — không tốn thêm API call tới GitLab, nhưng vẫn hữu ích để tiết kiệm thời gian viết thông báo thủ công.

Mẹo: Luôn tách bước "tạo MR" và bước "tự review MR" thành hai lượt prompt riêng như trên, đừng gộp vào một câu lệnh — tách bước giúp bạn có điểm dừng để đọc description agent sinh ra trước khi cho nó tiếp tục review, tránh trường hợp description sai mà review lại dựa trên description sai đó.

Hạn Chế Đã Biết Của GitLab MCP Trong OpenCode

Một số hạn chế thực tế cần biết trước khi đưa vào workflow chính thức của team:

  • Context window bị chiếm bởi MR lớn: Khi MR có diff hàng nghìn dòng, tool get_merge_request_diffs trả về toàn bộ nội dung, dễ làm đầy context window (cửa sổ ngữ cảnh) của model, khiến phần reasoning sau đó bị cắt ngắn hoặc model "quên" chỉ dẫn ban đầu. Giải pháp thực tế: yêu cầu agent chỉ lấy diff theo từng file cụ thể (git diff -- path/to/file) thay vì toàn bộ MR.
  • Rate limit GitLab API dễ bị đụng khi loop nhiều issue: Nếu bạn yêu cầu agent xử lý một list dài (ví dụ "đóng tất cả issue đã stale quá 90 ngày"), mỗi issue tốn ít nhất 2 API call (get + update). Với GitLab self-hosted có rate limit thấp, agent có thể bị 429 giữa chừng và dừng lại không rõ lý do. Nên giới hạn batch size (ví dụ xử lý tối đa 10 issue/lần) khi ra lệnh.
  • OpenCode chưa có UI diff trực quan như VS Code extension: Review MR qua terminal buộc bạn đọc diff dạng text thuần, không có syntax highlight side-by-side như trong IDE — với MR phức tạp, vẫn nên mở GitLab web UI để xác nhận lại trước khi approve merge.
  • Một số tool GitLab MCP server yêu cầu quyền Maintainer: Ví dụ tool xóa branch, protect branch. Nếu access token chỉ có quyền Developer, agent sẽ nhận lỗi 403 mà không tự biết nguyên nhân là do phân quyền GitLab chứ không phải do MCP config sai.

Mẹo: Khi agent báo lỗi khó hiểu từ GitLab MCP, luôn yêu cầu nó "show me the raw error response from the tool call" trước khi tự đoán nguyên nhân — nhiều lỗi 403/429 bị model diễn giải sai thành "MR không tồn tại" trong khi thực chất là vấn đề quyền hoặc rate limit.

Mẹo Thực Chiến

Vài kinh nghiệm khi vận hành GitLab MCP với OpenCode trong công việc hàng ngày:

  • Nếu team dùng nhiều LLM provider khác nhau cho OpenCode (ví dụ dev A dùng Claude, dev B dùng GPT), test kỹ hành vi tool-calling GitLab MCP với từng model — không phải model nào cũng chọn đúng tool ở prompt phức tạp nhiều bước như nhau.
  • Log toàn bộ session OpenCode có gọi GitLab MCP write action (tạo MR, merge, đóng issue) vào file riêng bằng flag --log-level debug > opencode-mcp.log, để có audit trail khi cần review lại "ai/cái gì đã tạo MR này lúc mấy giờ".
  • Với project có nhiều GitLab group con, luôn dùng project path đầy đủ (group/subgroup/project) trong prompt, tránh để agent tự search_projects — vừa chậm vừa có rủi ro chọn sai project trùng tên ở group khác.

Mẹo: Định kỳ mỗi sprint, review lại danh sách permission.mcp trong opencode.json — khi GitLab MCP server ra version mới thêm tool, tool mới mặc định thường rơi vào nhóm "ask", nên rà soát để bổ sung vào allow/deny list phù hợp thay vì để mặc định gây phiền khi dùng.

Tiếp GitLab MCP với Gemini CLI