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

status, created, owner

status	created	owner
shipped	2026-05-04	tbd

GitLab Integration

Why

Kandev's code-host integration is GitHub-only: PR browsing, review queue, issue watches, repo cloning, and the agent pr skill all assume github.com and the gh CLI. Users on GitLab (gitlab.com or self-managed) can't connect their account, can't see their merge requests in the MyGitHub-style page, can't have agents auto-clone or open MRs, and have to manually paste tokens for each task. This excludes a large chunk of professional users — and self-managed GitLab is common in regulated/enterprise environments where users have no choice. Tracked in #820.

What

• A GitLab integration runs alongside the GitHub one. Both can be configured at the same time; neither replaces the other.
• Users authenticate GitLab per Kandev workspace via one of:
  • glab CLI (auto-detected if installed and logged in).
  • Personal access token stored in the secret store for that workspace (or set via GITLAB_TOKEN on the backend host as a process-wide fallback).
• Self-managed instances are supported by configuring a GitLab host URL per workspace (default https://gitlab.com). The host applies to API calls, clone URLs, and web links for that workspace.
• Repositories can be added with provider = "gitlab". The repo cloner builds SSH (git@<host>:<owner>/<name>.git) and HTTPS clone URLs against the configured host, and authenticates HTTPS clones with the GitLab token when one is available.
• A "GitLab" page mirrors the existing GitHub page: a sidebar of MR / issue presets, a search bar, paginated lists, save-preset support, and the quick-task launcher. MRs are labelled "Merge requests" throughout the UI; the underlying state model is shared with PRs (open/closed/merged, draft, approvals, pipelines).
• For an MR linked to a task, the agent UI shows the same review surface it shows for PRs: title, description, head/base branches, mergeable state, approval status, pipeline status, and threaded discussions.
• A review-watch and an issue-watch poller mirror the GitHub ones: users can subscribe to MRs needing their review, or to GitLab issues matching a filter, and Kandev creates tasks when matches appear.
• The agent pr skill works for GitLab repos: when the task's repo is provider = "gitlab", the skill opens a merge request via glab (or the REST API with the stored token), targeting the same base branch logic used for GitHub.
• Settings live under /settings/integrations/gitlab with a page parallel to the GitHub one: workspace selector, connection status, host URL field, auth method (CLI vs PAT), reconnect CTA, token field that writes to the secret store, and a copy action for duplicating the config to another workspace.
• The orchestrator and credential providers pass GITLAB_TOKEN into agent environments the same way GITHUB_TOKEN is passed today, so agents running in containers can run glab or git push without extra setup.

Scenarios

• GIVEN a user with glab authenticated against gitlab.com, WHEN they open Kandev for the first time, THEN the GitLab integration shows as connected without requiring any manual token entry, and their merge requests appear on the GitLab page.

• GIVEN a user on a self-managed GitLab at https://gitlab.acme.corp, WHEN they enter the host URL and a personal access token in Settings → Integrations → GitLab for Workspace A, THEN Workspace A's connection status flips to connected, MR/issue lists populate against the custom host, and clone URLs for Workspace A repos use gitlab.acme.corp.

• GIVEN a task whose repository has provider = "gitlab", WHEN the agent runs the pr skill, THEN a merge request is opened on the configured GitLab host targeting the repo's default branch, and the MR URL is recorded against the task.

• GIVEN the user has a GitLab review watch for assignee=@me, WHEN a new MR is assigned to them upstream, THEN within one poll interval a Kandev task is created in the configured workflow step, linked to that MR.

• GIVEN GitLab is connected and GitHub is also connected, WHEN the user opens the kanban top bar, THEN both the GitHub and GitLab page buttons are visible and each lists items from its own provider only.

• GIVEN the user revokes their GitLab token externally, WHEN the background poller next runs, THEN the integration's status flips to "auth required" for the affected workspace with a reconnect banner on the GitLab page and the settings page, and no further API calls are issued for that workspace until the user reconnects.

• GIVEN no GitLab auth is configured, WHEN the GitLab page is opened, THEN it shows a "not connected" notice linking to settings, and no network calls are made to any GitLab host.

Out of scope

• GitLab webhook ingestion. v1 polls only, like the GitHub integration.
• GitLab CI pipeline editing or job log streaming inside Kandev. Pipeline status is shown read-only as part of MR feedback.
• GitLab Issues used as a Jira/Linear-style task source (link issue → task with state syncing, structured field mapping). Kandev's Jira and Linear integrations cover that pattern; this spec treats GitLab as a code host parallel to GitHub, not a project-tracker integration.
• Group-level MR / issue listings outside the user's own scope (no org-wide dashboards in v1).
• GitLab-specific features without a GitHub analogue: approval rules editing, protected-branch management, MR templates authoring, Duo / GitLab AI integration.
• OAuth login via GitLab as a Kandev sign-in method.
• Migration tooling for moving tasks/repos between GitHub and GitLab.
• Bitbucket. The placeholder in repoclone/protocol.go stays a placeholder.