# How to Integrate Tuicr with GitLab: Complete Setup and Configuration Guide

> Integrate Tuicr with GitLab easily by following this setup and configuration guide. Learn how to connect Tuicr to your GitLab repository for seamless merge request operations.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-01

---

**Tuicr integrates with GitLab automatically when the `glab` CLI is installed and authenticated, using the `GitLabGlabBackend` type in [`src/forge/gitlab/glab.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/glab.rs) to execute merge request operations via shell commands.**

Tuicr is an open-source terminal UI code review tool that provides native GitLab support through a dedicated backend implementation. When you integrate Tuicr with GitLab, the application detects GitLab remotes in [`src/vcs/git/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/mod.rs) and instantiates a `GitLabGlabBackend` that delegates all merge request operations—listing, diffing, and reviewing—to the official GitLab CLI (`glab`).

## Prerequisites

Before using Tuicr with GitLab, ensure you have the following:

- **Glab CLI**: A working `glab` executable available in your `$PATH`
- **Authentication**: A valid `glab` authentication token with at least `read_api` and `write_repository` scopes obtained via `glab auth login`
- **Repository Access**: Clone access to the GitLab repository you intend to review

If `glab` is missing or authentication fails, the backend returns a clear `TuicrError::Forge` error (see `map_glab_error` in [`src/forge/gitlab/glab.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/glab.rs)).

## How the GitLab Integration Works

Tuicr’s GitLab integration relies on a trait-based architecture that abstracts forge operations behind a common interface.

### Core Components

The integration centers on several key types defined in [`src/forge/gitlab/glab.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/glab.rs):

- **`GitLabGlabBackend`**: Implements the `ForgeBackend` trait (defined in [`src/forge/traits.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/traits.rs)) to provide GitLab-specific MR operations including `list_pull_requests`, `get_pull_request_diff`, and `create_review`
- **`GlabCommandRunner`**: Executes `glab` shell commands and captures stdout/stderr, converting non-zero exit codes into structured `TuicrError` instances
- **Parser Functions**: `parse_gitlab_remote_url` and `parse_pull_request_target_gitlab` convert remote URLs and MR identifiers (such as `owner/repo#42`, full URLs, or numeric IIDs) into `PullRequestTarget` structs
- **Data Models**: [`src/forge/gitlab/models.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/models.rs) defines Rust structs like `GlabMrSummary`, `GlabMrDetails`, and `GlabDiscussion` that deserialize JSON responses from `glab`

### Execution Flow

When you execute a Tuicr command targeting a GitLab merge request, the following occurs:

1. **Remote Detection**: [`src/vcs/git/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/mod.rs) parses the repository’s remote URL to identify GitLab hosts (including self-managed instances recognized by `glab config get host`)
2. **Backend Selection**: Tuicr constructs a `GitLabGlabBackend` instance when a GitLab remote is detected
3. **Command Execution**: Backend methods build `glab` CLI arguments (e.g., `glab mr view 42 --repo owner/repo --output json`) and execute them via `run_glab`
4. **Diff Processing**: `get_pull_request_diff` calls `inject_git_diff_headers` to add Git-style `diff --git` headers that `glab mr diff` omits, ensuring compatibility with Tuicr’s diff parser
5. **Review Submission**: `create_review` posts general MR notes and converts inline comments into GitLab "position" objects, sending them via `glab api` or GraphQL mutations for "request changes" actions

## Step-by-Step Configuration

### Install the GitLab CLI

Install `glab` using your package manager:

```bash

# macOS (Homebrew)

brew install glab

# Linux (check glab documentation for distribution-specific methods)

```

### Authenticate with GitLab

Generate a personal access token with `read_api` and `write_repository` scopes, then run:

```bash
glab auth login --hostname gitlab.com

```

The first time you run a Tuicr command without proper authentication, you’ll see: "GitLab integration requires `glab`. Install GitLab CLI and run `glab auth login`".

### Verify the Integration

Navigate to a GitLab repository clone and test the connection:

```bash
tuicr pr list

```

This triggers `GitLabGlabBackend::list_pull_requests`, which executes `glab mr list --repo owner/repo --output json --per-page 2`.

## Working with Merge Requests

### Opening Specific MRs

You can open merge requests using numeric IDs, full URLs, or the shorthand syntax:

```bash

# By MR number

tuicr pr 123

# By full URL

tuicr pr https://gitlab.com/owner/myproj/-/merge_requests/123

# By shorthand notation

tuicr pr owner/myproj#123

```

Tuicr resolves these via `parse_pull_request_target_gitlab` and calls `GitLabGlabBackend::get_pull_request` to fetch MR details.

### Listing and Filtering MRs

View open merge requests with optional filters:

```bash

# Show first page of all open MRs

tuicr pr list

# Show only MRs requesting your review

tuicr pr list --review-requested

```

The backend constructs the appropriate `glab mr list` command, adding `--reviewer=@me` when filtering for review requests.

### Submitting Reviews and Inline Comments

To add inline comments:

1. Navigate to a line in the diff view
2. Press `Ctrl-C` to open the comment dialog
3. Type your comment and press `Ctrl-S` to save

When ready to submit, use the command palette (`:`):

```bash
:submit comment        # Post comments without approval

:submit approve        # Approve the MR

:submit request-changes # Request changes via GraphQL mutation

:submit draft          # Save as draft notes using the draft_notes endpoint

```

The `create_review` method constructs JSON payloads like:

```json
{
  "body": "Looks good!",
  "position": {
    "position_type": "text",
    "base_sha": "...",
    "start_sha": "...",
    "head_sha": "...",
    "old_path": "src/lib.rs",
    "new_path": "src/lib.rs",
    "new_line": 42
  }
}

```

It sends these via `glab api projects/owner%2Frepo/merge_requests/123/discussions --method POST`.

## Key Implementation Files

The GitLab integration spans these source files in the `agavra/tuicr` repository:

- **[`src/forge/gitlab/glab.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/glab.rs)**: Core backend implementation (`GitLabGlabBackend`, `GlabCommandRunner`, `parse_gitlab_remote_url`)
- **[`src/forge/gitlab/models.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/models.rs)**: JSON deserialization structs (`GlabMrSummary`, `GlabDiscussion`)
- **[`src/forge/traits.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/traits.rs)**: `ForgeBackend` trait definition common to all forge backends
- **[`src/forge/selector.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/selector.rs)**: UI state machine for the "Pull Requests" tab that paginates via `list_pull_requests`
- **[`src/forge/remote_comments.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/remote_comments.rs)**: Converts GitLab discussion objects into `RemoteReviewThread` structs for the comment navigator
- **[`src/vcs/git/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/mod.rs)**: Remote URL detection and forge backend selection logic

## Summary

- Tuicr integrates with GitLab through the **`GitLabGlabBackend`** type, which implements the **`ForgeBackend`** trait to provide unified MR operations.
- The integration requires the **`glab`** CLI tool to be installed and authenticated with appropriate GitLab token scopes (`read_api`, `write_repository`).
- Remote detection occurs automatically in **[`src/vcs/git/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/mod.rs)**, selecting the GitLab backend for `gitlab.com` and recognized self-hosted instances.
- All MR operations—including listing, diffing, and reviewing—execute via **`glab`** shell commands managed by **`GlabCommandRunner`**.
- Review submissions support multiple states (comment, approve, request changes, draft) using both REST and GraphQL endpoints.

## Frequently Asked Questions

### What happens if `glab` is not installed?

Tuicr displays a clear error message: "GitLab integration requires `glab`. Install GitLab CLI and run `glab auth login`". The error originates from `GitLabGlabBackend` initialization in [`src/forge/gitlab/glab.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/glab.rs) when the executable is not found in `$PATH`.

### Does Tuicr support self-hosted GitLab instances?

Yes. Tuicr detects self-hosted GitLab instances when they are configured in your `glab` configuration (`glab config get host`). The `parse_gitlab_remote_url` function in [`src/forge/gitlab/glab.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/glab.rs) handles various GitLab URL formats, and the backend uses the standard `glab` CLI which supports multiple hosts.

### How does Tuicr handle GitLab's diff format?

Since `glab mr diff` omits Git-style `diff --git` headers that Tuicr’s parser requires, the `get_pull_request_diff` method in `GitLabGlabBackend` calls `inject_git_diff_headers` to reconstruct proper diff headers before processing. This ensures compatibility with the diff parsing logic used across all forge backends.

### Can I use draft reviews with GitLab?

Yes. When you submit with `:submit draft`, Tuicr calls the `draft_notes` endpoint instead of posting directly to the MR discussions. This requires appropriate permissions on the GitLab project. The backend distinguishes draft submissions from final reviews through the `SubmitEvent` type and routes them to the appropriate `glab api` endpoints.