Skip to main content
GitLab Logo

​
GitLab

Code repository and version control

✅ Ready📖 Documentation Available

​
Overview

GitLab is an all-in-one DevOps platform that provides a unified application for the entire software development lifecycle. Trusted by engineering and operations teams to streamline the transition from code planning to production, it integrates source code management, continuous integration and continuous deployment (CI/CD), security testing, and project management tools into a single, cohesive ecosystem.

​
GitLab Data Structure

The connector understands various entities of GitLab. Projects → Code → Work items & Merge Requests → Comments/Attachments

​
What Gets Synced

The connector indexes the following content for AI-powered search:
  • Projects: All accessible projects and their code on the default branch
  • Work Items: All work items and their comments and attachments
  • Merge Requests: Same body, comment, and attachment coverage as work items, plus commit SHAs, changed files with patches (diffs), per-file review comments on the diff, and MR review submissions (approve / request changes / comment); assignee and created/updated timestamps
  • Comments: All comments on work items, merge requests, and review feedback
  • Attachments: All attachments on work items, merge requests, and comments

​
Configuration Guide

​
Authentication Method

The GitLab connector uses OAuth 2.0 for secure authentication.
OAuth 2.0 is used as it provides secure, token-based access without requiring users to share their passwords.

​
⚠️ Critical User Configuration Requirement

Each user in your organization must set their email address to be publicly visible in order for PipesHub to correctly assign permissions and make records accessible.

​
Why Email Visibility Matters

PipesHub uses email addresses to match GitLab users with their permissions. If a user’s email is hidden:
  • PipesHub cannot identify the user when syncing permissions
  • Records will appear invisible to that user even if they have proper access in GitLab
  • The user won’t be able to see any content they should have access to

​
How to Configure Email Visibility

Every user must complete these steps in their GitLab account:
  1. Sign in to your GitLab account.
  2. Click on your Profile picture in the top right → Select “Edit profile”
Access User Profile
  1. Select the “Profile” tab
  2. Scroll down to the “Public email” section
  3. Choose the email address to show on your public profile
Set public email
  1. Click Update profile settings to save updated details
DO NOT select “Do not show on profile” - this will prevent PipesHub from accessing your email address and matching you to permissions, making all records invisible to you.
This is a per-user setting that must be configured by each individual user in your organization. Administrators cannot change this setting for other users. We recommend communicating this requirement to your team during the GitLab connector rollout.

​
Generating Client ID and Secret

​
Step 1: Access GitLab Applications

  1. Navigate to GitLab applications: Go to user_settings/applications and sign in with your GitLab credentials.
  2. View Your Apps: You’ll see the “Applications” page where you can create and manage OAuth 2.0 applications.
GitLab Applications Page

​
Step 2: Create a New OAuth 2.0 Application

  1. Click the “Add new application” button in the top right corner
  2. Fill in the application details:
    • Name: Enter a meaningful name (e.g., “PipesHub GitLab Connector”)
    • Redirect URI:
    • You need to enter the redirect URI provided by PipesHub
    • To get this URL, open PipesHub in another tab, navigate to PipesHub (bottom left corner) → Workspace settings → Connectors, find the Gitlab connector, and click “Setup”
    • Copy the Redirect URL shown in the configuration dialog:
    PipesHub GitLab Configuration - Copy Redirect URL
    • Select the following scopes:
      • read_user
      • read_repository
      • read_api
  3. Click “Save application” to proceed, a confirmation page will be shown with application details.
GitLab Application Confirmation

​
Step 3: Get OAuth Credentials

  1. Copy the following credentials:
    • Application ID: Your app’s unique identifier
    • Secret: Your app’s client secret
Store the Application ID and Secret securely. The secret can be regenerated if needed, but you’ll need to update your PipesHub configuration with the new value.

​
Step 4: Configure Connector in PipesHub

  1. Return to the PipesHub GitLab configuration dialog (if you closed it, navigate to PipesHub (bottom left corner) → Workspace settings → Connectors, find the Gitlab connector, and click “Setup”)
  2. The configuration dialog has two steps:
    • Step 1: Authentication - Enter OAuth credentials
    • Step 2: Sync Settings - Configure synchronization
  3. Verify the Redirect URI displayed matches the callback URL you configured in GitLab Applications (Step 2)
  4. Enter your OAuth 2.0 credentials:
    • Application (Client) ID: From previous step
    • Client Secret: From previous step
Enter OAuth Credentials in PipesHub
  1. Click “Next” to move forward

​
Step 5: Authorize the Connection

  1. After saving the configuration, click “Authenticate GitLab to Proceed”
  2. You’ll be redirected to GitLab’s authorization page
GitLab sign-in redirect
  1. Enter GitLab login credentials and click Sign In
  2. User will be shown the set of permissions needed, click Authorize to grant permissions
GitLab permissions page
  1. You’ll be redirected back to PipesHub with a success message
  2. The connector status will update to show “Connected — you can continue to Configure records”
GitLab OAuth completed

​
Step 6: Enable and Configure the Connector

  1. After successful authentication, click “Continue to configuration” to activate the connector
  2. A configuration dialog will appear with a section:
    • Sync Settings - Configure synchronization strategy and schedule
Sync settings GitLab Connector

​
Sync Settings

Configure your synchronization preferences:
  1. Sync Strategy: Choose between “Scheduled” or “Manual”
  2. Sync Interval: Choose how often to sync (default: 60 minutes)
Scheduled sync runs automatically at the specified intervals, keeping your data up-to-date without manual intervention. Manual sync requires you to trigger synchronization on-demand.

​
Save and Activate

  1. Click “Save Configuration” to save your configuration.
  2. User will be prompted to begin synchronization.
  3. The connector will verify credentials and begin initial synchronization
  4. Monitor the Indexing Progress to track sync completion

​
Supported Features

The GitLab connector syncs the following data from your GitLab projects:
  • Projects: All accessible projects and their code on the default branch
  • Work Items: All work items (issues, tasks, and incidents) content including description, status, comments
  • Merge Requests: Full merge request content including description, merge status, commit history, review comments, comments and file changes
  • Comments: All comments on work items, merge requests with author information
  • Attachments: Files attached to work items, merge requests (images, documents, etc.)

​
Troubleshooting

​
Common Issues

Invalid client credentials error:
  • Verify Client ID and Client Secret are correct
  • Ensure you copied the full values without extra spaces
  • Check that the OAuth app is active in GitLab applications
  • Regenerate the secret if necessary and update PipesHub
Callback URL mismatch error:
  • Ensure the Redirect URI in PipesHub exactly matches the callback URL in GitLab
  • Check for trailing slashes or protocol differences (http vs https)
  • Update both configurations to use the same URL
Authorization failed:
  • Verify you’re signing in with a valid GitLab account that has access to the required projects
No data syncing:
  • Verify the connector status shows “Active”
  • Check that the authenticating user has owned projects
  • Review sync logs for specific error messages
Token expired or sync stopped:
  • Disable and re-enable the connector to re-authenticate
  • Check if the OAuth app is still active in GitLab applications
If you modify OAuth application settings in GitLab applications (Client ID, Secret, callback URL), you must update the configuration in PipesHub and re-authorize the connection.

​
Connector Workflow

The GitLab connector follows a structured synchronization process to ensure all data is accurately synced and permissions are properly maintained.

​
Sync Overview

The run_sync method executes a complete synchronization cycle in a specific order:

​
Full Sync vs Incremental Sync

The connector automatically determines whether to perform a full or incremental sync:Full Sync occurs when:
  • First-time synchronization (no sync checkpoint exists)
  • Manual full sync is triggered
Incremental Sync occurs when:
  • A valid sync checkpoint exists
  • Uses the saved sync checkpoint to fetch or filter for records updated since the last sync time

​
User Synchronization

  1. User Fetch: Retrieves all users from GitLab groups and projects with their account IDs and emails

​
Project Synchronization

  1. Project Fetch: Retrieves all projects from GitLab with their code, work-items and merge-requests
  2. Role Assignment: Syncs project-specific roles (Guest, Planner, Developer, etc.)

​
Code Repository Synchronization

  1. Code Repository Fetch: Retrieves the code repository of the project on the default branch

​
Work Item Synchronization

For each project, the connector fetches work-items and merge-requests from the GitLab API. Each record is normalized into a hierarchical BlockGroup layout inside a BlocksContainer: the description, conversation, and (for merge requests) code-review context are kept in separate block groups so search and retrieval can target the right slice of content.

​
Body, comments, and attachments

For each work-item and merge-request, the connector:
  • Description: Stores the body as the first BlockGroup (index 0). Markdown is preserved and inline images are embedded in the indexed representation.
  • Comments: Stores each top-level comment as its own BlockGroup in thread order.
  • Attachments and images: Applies the same extraction and placement rules for work-items and merge-requests—files and images are mapped to the description or the specific comment they belong to.
Merge requests use the same body, comment, and attachment handling as work items. The section below lists additional content indexed only for merge requests.

​
Additionally for merge requests

  • Commits: Commit SHAs (and related commit context) are synced as dedicated blocks so answers can be tied to the commits on the MR.
  • Changed files: For files touched by the MR, the connector indexes file content together with the diff (patch) for that change.
  • Review comments on the diff: Per-file review comments on the MR changes—including line-associated feedback where GitLab provides it—are indexed separately from regular work items / merge requests conversation comments.

​
Sync pipeline (summary)

  1. Fetch all work items and merge requests for the project (respecting full vs incremental sync rules above).
  2. Batch records for processing.
  3. Build BlockGroups for description and comments; map attachments and images to the description or the correct comment.
  4. For merge requests only, add blocks for commits, changed files with diffs, review comments on changes, and review submissions.
Comments are stored as BlockGroups within the parent work item or merge request BlocksContainer (not as separate top-level records). That keeps threads organized and ensures comments are removed when the parent record is deleted.

​
Checkpoint Management

After each successful sync:
  • Stores the latest work items, merge requests update timestamps as checkpoint for each project

​
FAQ

Common causes:
  1. Email mismatch - The email used during connector authentication doesn’t match your PipesHub account email. This causes permission issues preventing you from accessing synced data.
    • Fix: Reconfigure the connector and authenticate using the same email as your PipesHub account.
  2. Data not yet indexed - The connector is still syncing or hasn’t completed the initial indexing process.
    • Fix: Go to Settings > Connectors, check the sync status, and wait for indexing to complete.
The initial sync duration depends on the size of your GitLab projects:
The most common causes are missing scopes or selecting the wrong GitLab account. Re-run authentication, ensure the PipesHub email and GitLab account emails match.

​
Need Help Getting Started?

Connect your GitLab account to PipesHub in just a few minutes. Follow the step-by-step guide above to enable project code, work items and merge-requests search across all your GitLab content.