kandev/docs/specs/gitlab-integration/plan.md

# GitLab Integration — Implementation Plan

**Spec:** `./spec.md`
**Issue:** [#820](https://github.com/kdlbs/kandev/issues/820)

## 1. Architecture decisions

**One package, mirror don't merge.** A new `internal/gitlab/` package mirrors
the layout of `internal/github/`. Do **not** introduce a unifying
`codehost.Client` interface in v1. The GitHub package is ~14k LOC and encodes
deep GitHub-specific knowledge (search query DSL, review states, mergeable
states, action presets). Premature abstraction would hurt both packages.
Defer the unifying interface to v2 — once the GitLab package is real, the
shared shape is concrete instead of guessed.

**Two clients, both shipped in v1.** Implement `pat_client.go` against
GitLab REST API v4 (Go HTTP client, similar shape to
`internal/github/pat_client.go`) **and** `glab_client.go` that shells out
to the `glab` CLI (similar shape to `internal/github/gh_client.go`).
`factory.go` selects: mock env var → `glab` CLI if installed and
authenticated → PAT (env var, then secrets store) → noop. Same selection
order as the GitHub package so users with `glab` already configured pick
up zero-config, and PAT remains the path for headless / corp-managed
environments.

**Auth: token-based, per-workspace host.** Token in `secrets.SecretStore`
under name `GITLAB_TOKEN` (env var `GITLAB_TOKEN` also accepted). Self-managed
host URL stored as a per-workspace setting (`gitlab_host`, default
`https://gitlab.com`). Per-workspace because different workspaces commonly
target different GitLab instances (work vs personal).

**Data model: parallel tables, shared field semantics.** New tables
`gitlab_mr_watches`, `gitlab_review_watches`, `gitlab_issue_watches`,
`gitlab_action_presets` parallel to their `github_*` counterparts. The
existing `Repository.Provider` field already supports `"gitlab"`; no schema
change there. PR/MR data is **not** unified — they're sibling concepts with
different fields (e.g. GitLab pipelines vs GitHub checks, GitLab approvals
vs GitHub reviews).

**`pr` skill: provider-aware, single skill.** Update `.agents/skills/pr/`
to detect the repo provider from `git remote` and branch on host. For GitLab
repos, use REST API directly via `curl`+`GITLAB_TOKEN` — no `glab`
dependency in the agent container.

## 2. File map

### Backend — new package `internal/gitlab/`

Mirrors `internal/github/` (~40 files) but deliberately smaller in v1. Files
to create:

- `models.go` — `MR`, `MRReview` (approvals), `MRComment`, `Pipeline`,
  `MRFeedback`, `MRStatus`, `MRSearchPage`, `Issue`, `IssueSearchPage`,
  `Project`, `RepoBranch`, `MRWatch`, `ReviewWatch`, `IssueWatch`. Shape
  parallel to `github/models.go` so frontend stores can share component
  families.
- `client.go` — `Client` interface (parallel to GitHub's, but with
  GitLab nouns: `GetMR`, `FindMRByBranch`, `ListAuthoredMRs`,
  `ListReviewRequestedMRs`, `SubmitMRApproval`, `ListPipelines`,
  `GetMRDiscussions`, `ResolveDiscussion`, `CreateMRDiscussionNote`).
- `pat_client.go` — REST v4 implementation. Per-instance host URL.
  Uses `PRIVATE-TOKEN` header for auth. Methods needed:
  - Projects: `/projects?membership=true`, `/projects/:id`, `/projects/:id/repository/branches`.
  - MRs: `/projects/:id/merge_requests`, `/merge_requests` (search),
    `/projects/:id/merge_requests/:iid`,
    `/projects/:id/merge_requests/:iid/discussions` (read + post + resolve),
    `/projects/:id/merge_requests/:iid/approvals`,
    `/projects/:id/merge_requests/:iid/changes`,
    `/projects/:id/merge_requests/:iid/commits`.
  - Pipelines: `/projects/:id/pipelines`, `/projects/:id/pipelines/:pipeline_id/jobs`.
  - Issues: `/issues` (search), `/projects/:id/issues/:iid`.
  - User: `/user` (auth check + login).
- `pat_client_test.go` — table-driven tests with `httptest.Server` per
  endpoint group, mirroring `github/pat_client_test.go`.
- `glab_client.go` — shells out to `glab` CLI for the same `Client`
  interface. Mirrors `internal/github/gh_client.go`: `GLabAvailable()`
  detects the binary, `IsAuthenticated()` runs `glab auth status`, and
  each method composes a `glab api …` or `glab mr …` invocation,
  parsing JSON stdout. Where `glab` lacks a direct command (e.g. specific
  search filters), fall through to `glab api` against the REST endpoint.
- `glab_client_test.go` — uses `exec.LookPath` shimming and a
  fake `glab` binary on `PATH` (same pattern as `gh_client_test.go`).
- `mock_client.go` + `mock_client_test.go` + `mock_controller.go` —
  E2E mock surface, gated by `KANDEV_MOCK_GITLAB=true`. Uses the
  `internal/integrations` shared shapes? **No** — copy the GitHub pattern
  (the mock currently lives outside `internal/integrations`). Match
  whichever pattern the team has standardized on (Linear/Jira use
  `internal/integrations`; GitHub does not). For consistency with
  GitHub-the-code-host, follow the GitHub pattern.
- `noop_client.go` — null-object fallback when unauthenticated.
- `factory.go` — `NewClient(ctx, secrets, host, log)`. Order: mock env
  var → `glab` CLI (if installed and authenticated for the configured
  host) → PAT (env var `GITLAB_TOKEN`, then secrets store key
  `GITLAB_TOKEN`) → noop.
- `service.go` — coordinator parallel to `github.Service`. Accepts the
  per-workspace host. Methods: status, MR list/search, MR feedback (incl.
  discussions), watches CRUD, action presets CRUD, sync. **Use
  `internal/integrations/healthpoll`** for the auth-health loop — that's
  the shared utility Jira/Linear already use, and the GitHub package
  predates it. New code should pick the better pattern.
- `service_*_test.go` — tests for issue, status, sync, watches, search
  cache (parallel to GitHub's split).
- `service_task_events.go` — subscribes to task events and resyncs when
  MRs are linked. Mirror GitHub.
- `store.go` — SQLx persistence for the four new tables + watches/presets
  read/write. Migrations next.
- `store_test.go` — multi-project / multi-workspace round-trip.
- `controller.go` — HTTP routes under `/api/v1/gitlab/*`:
  `GET /status`, `GET/POST/PUT/DELETE /mr-watches`,
  `GET/POST/PUT/DELETE /review-watches`,
  `GET/POST/PUT/DELETE /issue-watches`,
  `GET /mrs/:projectId/:iid/feedback`, etc.
- `handlers.go` — WS dispatcher registrations
  (`ActionGitLabStatus`, `ActionGitLabMRList`, …).
- `poller.go` — review-watch + issue-watch background loop. Reuse
  `healthpoll.Poller` for auth health; keep MR/issue polling in this
  package (different cadence, payload-shaped).
- `connectivity.go`, `constants.go`, `ttl_cache.go` — verbatim parallels.
- `provider.go` — `Provide(writer, reader *sqlx.DB, secrets SecretStore,
  eventBus bus.EventBus, log *logger.Logger) (*Service, func() error, error)`.

### Backend — schema migrations

- `apps/backend/internal/task/repository/migrations/NNNN_gitlab_tables.sql` —
  create `gitlab_mr_watches`, `gitlab_review_watches`,
  `gitlab_issue_watches`, `gitlab_action_presets`. Use `gitlab_*` prefix
  on every column to avoid collisions when the unifying refactor lands.
- `apps/backend/internal/workspace/...` — add `gitlab_host` column to the
  workspace settings table (or, if workspace settings are JSON, add the
  field to the JSON shape). Default `https://gitlab.com`.

### Backend — wiring

- `cmd/kandev/services.go` — new `initGitLabService(...)` helper that
  resolves the per-workspace host (or a global default for unscoped
  callers) and wires the service.
- `cmd/kandev/helpers.go` — register routes via `gitlab.RegisterRoutes`
  and `gitlab.RegisterMockRoutes`.
- `internal/repoclone/protocol.go` — replace the `gitlab.com` hardcode
  with a host parameter. `CloneURL` signature gains `host string`. Update
  call sites in `internal/agent/lifecycle/executor_*.go` and
  `internal/orchestrator/executor/executor_execute.go` to pass the
  workspace's `gitlab_host` when `provider == "gitlab"`.
- `internal/agent/credentials/env_provider.go` — already lists
  `GITLAB_TOKEN` in `knownAPIKeyPatterns`. No change required.
- `internal/agent/lifecycle/default_scripts.go` — extend the default
  prepare script so HTTPS clones for GitLab use
  `https://oauth2:${GITLAB_TOKEN}@<host>/<owner>/<name>.git`. Existing
  GitHub equivalent is the model.

### Frontend — new pages and components

- `apps/web/app/gitlab/page.tsx` + `gitlab-page-client.tsx` — mirror of
  `app/github/`. SSR fetches `/api/v1/gitlab/status`, hydrates store.
- `apps/web/app/settings/integrations/gitlab/page.tsx` — mirror of
  `settings/integrations/github/page.tsx`. Hosts the
  `GitLabIntegrationPage` panel: connection status banner, host URL
  field, PAT field, reconnect CTA.
- `apps/web/components/gitlab/` — domain components. The MyGitHub
  component family (`my-github/pr-list`, `my-github/issue-list`,
  presets sidebar, search bar, action presets, save-preset dialog,
  pagination, list toolbar, quick task launcher) is large and tightly
  coupled to the GitHub data shape. Two viable approaches:
  - **(A) Extract shared components.** Move generic pieces (search bar,
    pagination, save-preset dialog, list toolbar, presets sidebar
    skeleton) into `components/code-host/` parameterised on item shape.
    Wire both `github` and `gitlab` to them. Higher upfront cost, no
    duplication.
  - **(B) Copy-and-adapt.** Duplicate the components folder, swap PR
    types for MR types. Lower upfront cost, two parallel codebases to
    maintain.
  - **Recommendation: (A) for shells, (B) for body.** Extract the
    container components (sidebar, toolbar, pagination, save dialog) —
    they're already provider-agnostic in shape. Copy the row renderers
    (`pr-row.tsx` → `mr-row.tsx`) where the visible fields differ
    (approvals vs reviews, pipelines vs checks).
- `apps/web/lib/state/slices/gitlab/` — new slice mirroring
  `slices/github/`. Same hydration patterns.
- `apps/web/hooks/domains/gitlab/` — `use-gitlab-status`, watches,
  search, action presets. Symmetric to `hooks/domains/github/`.
- `apps/web/lib/api/domains/gitlab-api.ts` — REST client.
- `apps/web/lib/types/gitlab.ts` — `GitLabMR`, `GitLabIssue`, etc.

### Frontend — kanban top-bar

- `apps/web/components/kanban/kanban-header.tsx` — add
  `GitLabTopbarButton` next to `GitHubTopbarButton`. Render only when
  GitLab is configured for the active workspace (gate on
  `useGitLabAvailable`).
- `apps/web/components/kanban/kanban-header-mobile.tsx` — same.

### Agent skill — `pr`

- `.agents/skills/pr/SKILL.md` — add a "GitLab repos" section
  explaining the detection (`git remote get-url origin` matches
  `:gitlab|/gitlab`) and the GitLab MR-creation flow. Prefer `glab` CLI
  if available in the agent container; fall back to REST API via `curl`
  with `GITLAB_TOKEN`. Keep `gh` as the GitHub path.
- `.claude/skills/pr/SKILL.md` symlink — already symlinked, no change.

### WebSocket actions

- `pkg/websocket/actions.go` (or wherever GitHub actions are declared) —
  add `ActionGitLabStatus`, `ActionGitLabMRList`, `ActionGitLabMRGet`,
  `ActionGitLabMRFeedbackGet`, watches (review/issue/MR), pipeline
  status, action presets, stats.

## 3. Phases

Each phase ends with `make fmt` then `make typecheck test lint` (backend)
and `pnpm typecheck test lint` (web).

### Phase 1 — Backend client + auth (no UI)

Goal: the backend can list one user's MRs over REST.

- `internal/gitlab/{models,client,pat_client,glab_client,noop_client,
  factory,connectivity,constants}.go` plus tests.
- Mock client + controller. Wired under `KANDEV_MOCK_GITLAB=true`.
- Provider + `cmd/kandev/services.go` `initGitLabService`.
- Status WS handler + `/api/v1/gitlab/status` HTTP route.
- Migration for the new tables (kept empty-but-present so future phases
  can write).
- Tests: PAT client per-endpoint, noop client, factory selection,
  controller status route.

### Phase 2 — Repo cloning + agent env

Goal: a GitLab repo can be cloned and the agent has the token.

- `repoclone/protocol.go` host parameter. Call-site updates.
- `lifecycle/default_scripts.go` HTTPS-with-token rewrite for GitLab.
- Workspace `gitlab_host` setting (read/write API + UI field deferred
  to Phase 3).
- Tests: protocol unit test for SSH/HTTPS variants on custom host.
  Lifecycle prepare-script test for token injection.

### Phase 3 — Settings page + connection UX

Goal: a user can connect/reconnect a GitLab account from the UI.

- `app/settings/integrations/gitlab/page.tsx` + panel.
- API endpoints: get/set host, set/clear token.
- Reuse `<IntegrationAuthStatusBanner>` and
  `<IntegrationAuthErrorMessage>` from `internal/integrations` if those
  shells fit (they were built for Linear/Jira; check shape compat first).
- Tests: settings panel render + token-save flow (vitest).

### Phase 4 — MR list page + watches

Goal: full feature parity with the GitHub page for browse + watch.

- Extract shared shells from GitHub MyGitHub components into
  `components/code-host/`.
- New `components/gitlab/my-gitlab/` — row renderers, search-bar
  preset definitions, action-presets resolution.
- `app/gitlab/page.tsx` + client.
- Watch CRUD WS handlers + UI.
- `gitlab` slice + hooks.
- Poller for review-watches and issue-watches (uses
  `healthpoll.Poller` for auth-health; MR/issue polling in
  `gitlab/poller.go`).
- Tests: store slice, hooks, save-preset, search.

### Phase 5 — MR review surface (#820 core)

Goal: the agent UI shows MR feedback (discussions, approvals, pipeline)
and the agent can post/resolve discussions.

- `GetMRDiscussions` + `CreateMRDiscussionNote` + `ResolveDiscussion`
  in `pat_client.go`.
- `MRFeedback` payload + `WS ActionGitLabMRFeedbackGet`.
- Frontend: in the existing PR-feedback panel that lives next to a
  task, branch on `provider`. Reuse the comments/threads UI; map
  GitLab discussions onto the same shape (discussion = thread, notes =
  comments, `resolved` flag).
- Tests: pat_client discussions round-trip, frontend feedback panel
  with a GitLab fixture.

### Phase 6 — `pr` skill update + #820 wiring

Goal: clicking "Create PR" on a GitLab task opens a real MR.

- `.agents/skills/pr/SKILL.md` — GitLab branch.
- The kanban "Create PR" button already runs the `pr` skill on the
  task; no new wiring needed. Verify the surfaced MR URL flows back
  through the existing PR-watch path (Phase 4 watches consume it).
- Manual smoke: open a kandev workspace pointing at a GitLab repo,
  edit, click Create PR, watch the MR appear, comment from gitlab.com,
  watch the agent see and resolve the comment.

### Phase 7 — Cleanup + docs

- Remove `// TODO: GitLab support is not yet implemented` from
  `repoclone/protocol.go`.
- Update `CLAUDE.md` "Repo Layout" and the integrations section to
  list `internal/gitlab/`.
- Add the new spec/plan to `docs/specs/INDEX.md` (already done) and
  flip status to `shipped` once merged.

### Phase 8 — MR auto-link (post-ship follow-on)

Goal: close the gap where an MR opened outside Kandev's own MR-creation action
(`glab mr create`, or opening the MR directly in the GitLab web UI) never got
linked — only manual URL linking and the Create-PR callback did. Mirrors
GitHub's push-detection auto-link.

- `internal/gitlab/service_task_mr_autolink.go` — `Service.AutoLinkMRForBranch`
  (find-MR-by-branch → validate repository identity → upsert association →
  ensure refresh watch → publish `gitlab.task_mr.updated`).
- `internal/gitlab/service_watches.go` — `EnsureMRWatch` (idempotent
  get-or-create) and `CheckMRWatch` now refresh `gitlab_task_mrs` on every
  poll, not just watch timestamps.
- `gitlab_mr_watches` unique key widened to `(session_id, repository_id,
  branch)` via an idempotent table-rebuild migration, so multi-branch tasks
  don't collide on the second branch's watch insert.
- `internal/orchestrator/event_handlers_gitlab_mr.go` — `detectPushAndAssociateMR`
  (GitLab twin of GitHub's `detectPushAndAssociatePR`, same `[0, 30s, 60s]`
  retry shape) and `CheckSessionMR` (on-demand check, mirrors `CheckSessionPR`).
  `event_handlers_git.go`'s push-tracking dispatches by repository provider so
  the two providers' code paths never call into each other's client.
  `Status: shipped.`

Out of scope for this phase (unchanged from the root spec): webhook-driven
linking, and backfilling associations for MRs opened before this shipped.

## 4. Risks / open points

- **API shape mismatches.** GitLab's MR discussions are nested
  (discussion → notes → resolved); GitHub's review comments are flat
  with `in_reply_to`. Mapping into the existing comments/threads store
  needs care — discussions are the natural unit on GitLab, not
  individual comments. Mitigation: GitLab discussions become first-class
  in the store, the GitHub side is mapped as "discussions of one note".
  Defer if it explodes scope; v1 can render two distinct components.
- **Action-preset query syntax.** GitHub presets use the GitHub search
  DSL (`is:pr is:open author:@me`). GitLab MR search uses query
  parameters (`?author_username=…&state=opened`). The presets feature is
  GitHub-shaped; v1 ships GitLab presets as a constrained set
  (assignee/author/reviewer × open/merged) without full DSL parity.
- **Self-managed TLS.** Self-hosted GitLabs sometimes use private CAs.
  `pat_client.go` uses the default `http.Client`. A workspace setting
  `gitlab_insecure_skip_verify` is the lazy answer; the right answer is
  reading `SSL_CERT_FILE`. v1 reads `SSL_CERT_FILE`; flag the
  self-signed escape hatch as a follow-up.
- **Per-workspace vs global host.** Per-workspace adds per-call
  resolution overhead and complicates non-workspace-scoped callers
  (review/issue pollers). Mitigation: the poller iterates workspaces
  and uses each workspace's host; the MyGitLab page is workspace-scoped
  by construction.
- **`glab` CLI parity.** `glab` lacks direct commands for some search
  filters that REST exposes; the CLI client falls back to `glab api`
  for those, which means the `glab` binary version matters less than
  the underlying REST endpoint version. Pin a minimum `glab` version
  in `GLabAvailable()` and surface the version mismatch in the
  status WS payload so the settings page can warn.
- **Frontend component extraction (Phase 4).** Risk of refactor churn
  on GitHub during the extraction. Mitigation: extract
  one-component-at-a-time behind matching tests; revert the extraction
  if scope creeps and just copy-and-adapt instead.
- **Mock harness scope.** GitHub's mock has 14k LOC of behavior to
  emulate; GitLab's mock can ship with a thin slice (status, MR list,
  MR feedback, watch round-trips). The Playwright e2e suite is the
  forcing function — match what tests need, not full parity.

## 5. Out of scope (per spec)

Webhook ingestion, GitLab CI editing, GitLab-Issues-as-tracker,
group-wide dashboards, OAuth login, Bitbucket. Two natural follow-ups
once shipped: webhook ingestion (kills the pollers) and the unifying
`codehost.Client` interface (now that two real clients exist).