# GitLab Integration & Agent Git Branch Workflow Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Allow users to connect GitLab (SaaS or Self-hosted) repositories, assign Git identities to Agents, and automatically clone, branch, commit, push, and open Merge Requests (MR) when Agents execute tasks on Machine runners.

**Architecture:** Extend `repositories` model to store `provider`, `gitlab_host`, and `access_token`. Update CLI `repoOps.ts` to support token-authenticated Git clones, branches, and pushes for both GitHub and GitLab. Add `gitlabService.ts` on the Web Server to interact with GitLab REST API (`POST /api/v4/projects/:id/merge_requests`) and update `pr_url` on tasks.

**Tech Stack:** Hono, D1/SQLite, Node.js WebCrypto, Git CLI, React (Vite UI).

---

### Task 1: Extend DB Schema & Repository API for GitLab Support

**Files:**
- Modify: `apps/web/server/db.ts:60-90`
- Modify: `apps/web/server/taskRepo.ts:1-50`
- Modify: `apps/web/server/routes.ts:1650-1700`

- [ ] **Step 1: Write failing test for GitLab repository creation**
- [ ] **Step 2: Run test to verify it fails**
- [ ] **Step 3: Add `provider`, `gitlab_host`, `access_token` to `repositories` schema and D1 migrations**
- [ ] **Step 4: Update `createRepository` & `listRepositories` in `taskRepo.ts` & `routes.ts`**
- [ ] **Step 5: Run test to verify it passes**
- [ ] **Step 6: Commit changes in Vietnamese**

---

### Task 2: Update CLI `repoOps.ts` for Token-authenticated Git Clone, Branch & Push

**Files:**
- Modify: `packages/cli/src/workspace/repoOps.ts:1-64`
- Modify: `packages/cli/src/daemon/dispatcher.ts:200-260`

- [ ] **Step 1: Write failing test for HTTPS token clone URL generation in `repoOps.test.ts`**
- [ ] **Step 2: Run test to verify it fails**
- [ ] **Step 3: Refactor `ensureCloned` to handle both GitHub (`gh repo clone`) and GitLab (`git clone https://oauth2:<token>@<host>/<path>.git`)**
- [ ] **Step 4: Add `pushAgentBranch(dir, branchName, repo)` helper function**
- [ ] **Step 5: Run tests to verify they pass**
- [ ] **Step 6: Commit changes in Vietnamese**

---

### Task 3: Implement GitLab Merge Request (MR) API Helper & Endpoint

**Files:**
- Create: `apps/web/server/gitlabService.ts`
- Modify: `apps/web/server/routes.ts:1800-1860`

- [ ] **Step 1: Write unit tests for `createGitLabMergeRequest` in `tests/gitlabService.test.ts`**
- [ ] **Step 2: Run test to verify it fails**
- [ ] **Step 3: Implement `gitlabService.ts` using GitLab REST API (`POST /api/v4/projects/:id/merge_requests`)**
- [ ] **Step 4: Add API route `POST /api/tasks/:id/gitlab-mr` to trigger MR creation and update `pr_url` on task**
- [ ] **Step 5: Run tests to verify they pass**
- [ ] **Step 6: Commit changes in Vietnamese**

---

### Task 4: Add Web UI GitLab Repository Form

**Files:**
- Modify: `apps/web/src/components/RepositoriesDrawer.tsx`
- Modify: `apps/web/src/components/CreateRepoModal.tsx`

- [ ] **Step 1: Add Provider toggle (GitHub / GitLab) in Create Repository dialog**
- [ ] **Step 2: Add GitLab Host input (default `gitlab.com`) and Personal Access Token (PAT) input**
- [ ] **Step 3: Verify build `pnpm --filter web build`**
- [ ] **Step 4: Commit changes in Vietnamese**