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

Tuicr integrates with GitLab automatically when the glab CLI is installed and authenticated, using the GitLabGlabBackend type in 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 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).

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:

• GitLabGlabBackend: Implements the ForgeBackend trait (defined in 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 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 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:

# 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:

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:

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:

# 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:

# 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 (:):

: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:

{
  "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: Core backend implementation (GitLabGlabBackend, GlabCommandRunner, parse_gitlab_remote_url)
• src/forge/gitlab/models.rs: JSON deserialization structs (GlabMrSummary, GlabDiscussion)
• src/forge/traits.rs: ForgeBackend trait definition common to all forge backends
• src/forge/selector.rs: UI state machine for the "Pull Requests" tab that paginates via list_pull_requests
• src/forge/remote_comments.rs: Converts GitLab discussion objects into RemoteReviewThread structs for the comment navigator
• 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, 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}