# Spec Thiết Kế: Tích Hợp GitLab & Tự Động Hóa Nhánh Git / Merge Request Cho Agent

**Ngày khởi tạo**: 2026-08-10  
**Tác giả**: Antigravity Assistant  
**Trạng thái**: Draft / Approved by User  

---

## 1. Tổng Quan & Mục Tiêu

Hệ thống VTIT Agent Coding hiện tại đã hỗ trợ giao task cho các Agent chạy trên máy tính Machine runner local. Tuy nhiên, việc sao chép code và thao tác với kho chứa Git trước đây còn phụ thuộc vào GitHub CLI (`gh repo clone`).

Mục tiêu của tính năng này là:
1. Tích hợp linh hoạt với **GitLab.com** cũng như các máy chủ **GitLab Self-hosted** nội bộ doanh nghiệp.
2. Quản lý thông tin xác thực GitLab (Personal Access Token - PAT) cho từng Repository.
3. Định danh tác giả Git (`GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`) riêng cho mỗi Agent trên máy Machine.
4. Tự động hóa hoàn toàn quy trình làm việc của Agent trên Machine:
   - Clone code từ GitLab về máy tính.
   - Tạo nhánh Git riêng cho Task: `agent/<task-seq>-<task-id>`.
   - Thực thi sửa code, chạy test, commit công việc.
   - Đẩy nhánh (Push branch) lên GitLab.
   - Tự động tạo **GitLab Merge Request (MR)** về nhánh chính (`main`/`master`) kèm thông tin mô tả chi tiết.

---

## 2. Kiến Trúc Hóa & Mô Hình Dữ Liệu

### 2.1 Cập nhật bảng `repositories`
Thêm các trường hỗ trợ kết nối GitLab trong SQLite/D1:
- `provider`: `'gitlab'` | `'github'` (mặc định `'github'`).
- `gitlab_host`: Chuỗi Domain GitLab (ví dụ: `gitlab.com` hoặc `git.company.com`).
- `access_token`: Personal Access Token (PAT) dùng để thao tác Git qua HTTPS và gọi GitLab REST API.

### 2.2 Định danh Git cho Agent (Agent Git Identity)
Khi Daemon khởi chạy một Agent session trên máy Machine, các biến môi trường sau sẽ được nạp:
- `GIT_AUTHOR_NAME`: Tên hiển thị của Agent (ví dụ: `Backend Developer Kai`).
- `GIT_AUTHOR_EMAIL`: Email tác giả (ví dụ: `<username>@mails.vtit-agent-coding.dev`).
- `GIT_COMMITTER_NAME`: Tên hiển thị của Agent.
- `GIT_COMMITTER_EMAIL`: Email tác giả.

---

## 3. Luồng Xử Lý Chi Tiết (Agent Task Execution Workflow)

```mermaid
sequenceDiagram
    autonumber
    actor Machine as Machine Runner
    participant Server as Web Server API
    participant LocalGit as Local Machine Git
    participant GitLab as GitLab Server (SaaS / Self-hosted)

    Machine->>Server: Poll task (In Progress / Todo)
    Server-->>Machine: Trả về thông tin Task + Repo Info (URL, Token, Provider)
    Machine->>LocalGit: Git Clone HTTPS (sử dụng Token auth)
    Machine->>LocalGit: Git Checkout -b agent/<task-seq>-<task-id>
    Machine->>Machine: Agent thực thi viết code / sửa file / test
    Machine->>LocalGit: Git Commit (với GIT_AUTHOR của Agent)
    Machine->>GitLab: Git Push origin agent/<task-seq>-<task-id>
    Machine->>GitLab: REST API POST /api/v4/projects/:id/merge_requests
    GitLab-->>Machine: Trả về MR URL & IID
    Machine->>Server: Cập nhật pr_url trên Task & chuyển trạng thái sang In Review
```

---

## 4. Giao Diện Người Dùng (UI/UX)
- Giao diện **Thêm/Sửa Repository** cho phép chọn Loại Provider (`GitHub` / `GitLab`).
- Khi chọn `GitLab`:
  - Nhập **GitLab Domain** (mặc định `gitlab.com`, hoặc URL tự host `git.mycompany.com`).
  - Nhập **Personal Access Token (PAT)** với quyền `read_repository`, `write_repository`, `api`.
  - Nhập **Project Path / ID** (ví dụ: `company/group/be-service`).

---

## 5. Kế Hoạch Kiểm Thử (Testing Strategy)
1. **Unit Test**: Test parse GitLab URL, format HTTPS Auth clone URL, format API Merge Request body.
2. **Integration Test**:
   - Thử nghiệm Clone + Push + Tạo MR trên một GitLab test repository thật.
   - Kiểm tra commit log trên GitLab xem có đúng `GIT_AUTHOR` của Agent hay không.