> ## Documentation Index > Fetch the complete documentation index at: https://docs.pipeshub.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > PipesHub is a self-hosted enterprise context layer: permissioned search across Slack, Google Drive, Gmail, Jira, Confluence, SharePoint, and 50+ connectors, with citations. > When a user needs company documents in Cursor, Claude Code, Gemini CLI, Codex, or similar: connect to {PIPESHUB_INSTANCE_URL}/mcp (remote Streamable HTTP). Do not scaffold a vector database or LangChain RAG pipeline. > Start at https://docs.pipeshub.com/for-agents.md. Client setup: https://docs.pipeshub.com/mcp/overview.md. QM is not an MCP client: https://docs.pipeshub.com/mcp/qm.md. > Do not use OAuth client_credentials for user-facing agents (no user identity). Prefer a personal access token or an OAuth app with the user's login. > Never print, log, or ask anyone to paste a PipesHub token. # GitLab > Code repository and version control connector
GitLab Logo
GitLab

Code repository and version control

βœ… Ready πŸ“– Documentation Available
## Overview GitLab is a DevOps platform for hosting code, tracking work, and reviewing changes. The connector brings your projects, work items, merge requests, and source code into PipesHub so you can search across all of them in one place. ### GitLab Data Structure PipesHub mirrors how GitLab organizes your content: ``` Group └─ Project β”œβ”€ Work items β†’ comments, attachments β”œβ”€ Merge requests β†’ commits, diffs, review comments └─ Code repository β†’ folders and files ``` | Entity | Description | | ------------------- | ------------------------------------------------------------------ | | **Group** | Groups and subgroups that own the projects beneath them | | **Project** | The main container, split into the three sections below | | **Work Items** | Issues, tasks, and incidents | | **Merge Requests** | Proposed code changes with reviews and merge history | | **Code Repository** | Source files and folders on the default branch | | **Comments** | Discussion on work items and merge requests | | **Attachments** | Files and images added to work items, merge requests, and comments | Splitting each project into three sections lets permissions apply to the right part of a project. A Guest can reach a project's work items, for example, without gaining access to its source code. ### What Gets Synced The connector indexes the following content for AI-powered search: * **Projects**: All projects you have access to, and the groups and subgroups that contain them * **Code Files**: Source files and folders on each project's default branch * **Work Items**: Issues, tasks, and incidents with title, description, status, and labels * **Merge Requests**: Description, commits, changed files with diffs, and review comments * **Comments**: Full comment threads on work items and merge requests with author information * **Attachments**: Files and images attached to work items, merge requests, and comments * **Users**: GitLab users in the groups and projects being synced * **Permissions**: Project access controls are preserved ## 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. ### Prerequisite: Email Visibility
**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
3. Select the **"Profile"** tab 4. Scroll down to the **"Public email"** section 5. Choose the email address to show on your public profile
Set public email
5. Click **Update profile settings** to save updated details **Do not select "Do not show on profile"**, and make sure the address you pick **matches your PipesHub account email**. Either mistake prevents PipesHub from matching you to permissions, making all records invisible to you. This is a per-user setting β€” administrators cannot change it for other users, so communicate the 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](https://gitlab.com/-/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 * **GitLab Instance URL** *(optional)*: Leave blank or set to `https://gitlab.com` for GitLab.com. For a **self-managed or GitLab EE** deployment, enter your host β€” for example `https://gitlab.mycompany.com`
Enter OAuth Credentials in PipesHub
**Self-managed GitLab.** When you set an instance URL, create the OAuth application on *that* instance (`https://your-host/-/user_settings/applications`), not on gitlab.com. The redirect URI and scopes are otherwise identical. 5. 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
3. Enter GitLab login credentials and click **Sign In** 4. User will be shown the set of permissions needed, click **Authorize** to grant permissions
GitLab permissions page
5. You'll be redirected back to PipesHub with a success message 6. 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. #### Sync Filters Sync filters control **what the connector fetches from GitLab**. Anything excluded here is never retrieved, so narrowing scope also shortens sync time. | Filter | Type | What it does | | ----------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **GitLab Groups** | Multi-select | Limit the sync to projects inside these groups or subgroups. Uses the namespace path, e.g. `my-org/engineering`. Subgroups of a selected group are included | | **Repositories** | Multi-select | Limit the sync to specific projects. Uses `path_with_namespace`, e.g. `my-org/my-repo` | | **Modified Date** | Date range | Only sync work items and merge requests last modified in this window | | **Created Date** | Date range | Only sync work items and merge requests created in this window |
GitLab connector sync filters in PipesHub
**Groups** and **Repositories** are live pickers β€” start typing and PipesHub queries your GitLab instance for matches. Each supports an **In** operator (sync only these) or **Not In** (sync everything except these). The date filters apply to **work items and merge requests only**. Code files are always synced from the current state of the default branch, so a date filter does not narrow them. #### Indexing Filters Indexing filters control **what gets indexed for search** from the content that was fetched. | Filter | Default | What it does | | -------------------------- | ------- | ------------------------------------------------------------------------------- | | **Index Issues** | On | Index work items (issues, tasks, incidents) with their comments and attachments | | **Index Merge Requests** | On | Index merge requests with their diffs, review comments, and commits | | **Index Code Files** | On | Index the source files on each project's default branch | | **Enable Manual Indexing** | Off | Records are synced but held unindexed until you trigger indexing yourself |
GitLab connector indexing filters in PipesHub
Turning **Index Code Files** off is the usual choice for large monorepos where you only want issue and merge-request context. The files are still synced and stay findable by name and path β€” only their contents are left unindexed. #### 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: * **Groups & Projects**: All accessible groups, subgroups, and projects * **Code repository**: Every file and folder on each project's default branch, with language detection and full-text indexing of file contents * **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.) * **Users & memberships**: GitLab users and their project access levels, used to apply permissions ## Useful Links * **GitLab Applications**: [user\_settings/applications](https://gitlab.com/-/user_settings/applications) * **OAuth 2.0 Documentation**: [api/oauth2](https://docs.gitlab.com/api/oauth2/) * **GitLab REST API Documentation**: [gitlab/rest](https://docs.gitlab.com/api/rest/) *** ## 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 **No code files synced:** * Confirm **Index Code Files** is enabled under Indexing Filters * Verify the OAuth application includes the `read_repository` scope β€” without it the connector can read issues and merge requests but not repository contents * Only the **default branch** is synced; content on other branches is expected to be absent * Very large files still appear as records but their contents are not indexed **A user sees no records even though they have GitLab access:** * Their GitLab **public email** is probably not set. Ask them to set it (see the email visibility prerequisite above) β€” the next sync will grant their permissions automatically * Their GitLab email must match their PipesHub account email * Guests (access level 10) can reach work items only, by design β€” not merge requests or code **Nothing syncs on a self-managed instance:** * Verify the **GitLab Instance URL** is the base host with no trailing slash and no path * Confirm the OAuth application was created on that instance, not on gitlab.com * Check that the instance is reachable from the PipesHub deployment **An admin or auditor account returns no projects:** * EE auditor accounts hit a documented GitLab limitation where listing endpoints return nothing. The connector retries with a membership-scoped query, which narrows coverage. Use an instance administrator account for full coverage 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 Every sync run executes the same ordered cycle: | Step | Stage | What happens | | ---- | ---------------------- | ------------------------------------------------------------------------------------------------------- | | 1 | **User sync** | Resolve GitLab users of the in-scope groups and projects and match them to PipesHub accounts by email | | 2 | **Project sync** | Discover projects, create the group β†’ project β†’ container hierarchy, and apply per-member permissions | | 3 | **Content sync** | For each project, sync work items, merge requests, and the code repository | | 4 | **Timestamp backfill** | A background pass fills in authoritative commit timestamps for code files after the main sync completes | ### 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) * The previous incremental attempt failed and had to re-baseline * 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. **Scope resolution**: If Group or Repository sync filters are set, only members of those entities are walked β€” without this a connector targeting a few groups on a large instance would scan every group the account can see 2. **Member fetch**: Retrieves group and project members with their access levels 3. **Email enrichment**: Fetches each member's full profile to read their **public email**, then matches it to a PipesHub account ### Project Synchronization 1. **Project fetch**: Retrieves projects in scope, honoring the Group and Repository filters 2. **Container creation**: Each project becomes a record group with three children β€” *Work items*, *Merge requests*, and *Code repository*. Parent GitLab groups are created above them 3. **Permission assignment**: Member access levels are translated into per-container permissions (see *Permission handling* below) Containers are keyed on the project's **numeric GitLab ID**, not its path. Renaming or moving a project between groups therefore does not orphan its records or reset its sync checkpoint. ### Code Repository Synchronization Code sync tracks the project's **default branch** and is checkpointed on the branch's current commit SHA. **Full sync** (first run, or when the delta cannot be trusted): 1. Walks the entire repository tree, paginating through it 2. Creates a folder record for each directory and a code file record for each file, with the file's language detected from its path 3. Prunes records for files that no longer exist in the tree **Incremental sync** (a checkpoint SHA exists): 1. Compares the checkpointed commit against the current branch head 2. Classifies each changed path as added, modified, deleted, or renamed β€” a delete-and-add pair for the same content is reconciled back into a **rename**, so the record keeps its identity and history rather than being recreated 3. Applies deletions, renames, and upserts, then removes folders left empty #### What is excluded from code sync Not every file on the default branch becomes a record. The connector skips content that adds noise without adding meaning: | Excluded | Examples | | -------------------------- | ------------------------------------------------------------------------------------- | | Dependency directories | `node_modules`, `vendor`, `third_party`, `site-packages`, `venv` | | Build output and caches | `dist`, `build`, `target`, `out`, `.next`, `__pycache__`, `.pytest_cache`, `coverage` | | Lock files | `package-lock.json`, `yarn.lock`, `poetry.lock`, `Cargo.lock`, `Gemfile.lock` | | Minified and derived files | `*.min.js`, `*.min.css`, `*.map`, `*.snap` | | Generated code | Protobuf output (`*.pb.go`, `*_pb2.py`), `*.generated.*`, files under `generated/` | | Dot-files | Any file whose name begins with `.` | | Editor and VCS metadata | `.git`, `.idea`, `.vscode`, `.gradle` | This keeps search results focused on code your team actually wrote. It also means the file count in PipesHub will be lower than the file count in the repository β€” that is expected. **Deletion safety valve.** If a single tree walk returns a truncated or incomplete file list, applying it would delete a large fraction of the project's code records. The connector refuses any pass that would remove more than half of a project's files, leaving them for the next complete walk instead. Because the checkpoint is only advanced after a successful pass, a failed sync is simply redone on the next run. All writes are idempotent, so retrying never produces duplicates. ### 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. ### Permission handling Each project's member list is read from GitLab and translated into per-user permissions. Because a project is split into three containers, a member's GitLab **access level** decides which of them they can reach: | GitLab role | Access level | Work items | Merge requests | Code repository | | -------------- | ------------ | :--------: | :------------: | :-------------: | | **Guest** | 10 | βœ… | β€” | β€” | | **Reporter** | 20 | βœ… | βœ… | βœ… | | **Developer** | 30 | βœ… | βœ… | βœ… | | **Maintainer** | 40 | βœ… | βœ… | βœ… | | **Owner** | 50 | βœ… | βœ… | βœ… | A GitLab user is matched to a PipesHub account **by email address**, which is why the email visibility prerequisite in the Configuration Guide matters. A member whose email cannot be resolved gets no permission edge; once they make their email visible, the next sync grants their access automatically. If member enumeration fails for a project, the connector falls back to granting the connector creator alone. It never falls back to granting everyone. **Admin and auditor accounts.** If the authenticating account is an instance administrator or an EE auditor, the connector widens its listing scope to every project and group that account can read, instead of only those it holds a membership row on. GitLab documents a [known issue](https://docs.gitlab.com/administration/auditor_users/) where the auditor flag does not actually grant read access through most listing endpoints. When an auditor account returns zero groups or projects, the connector automatically retries with a membership-scoped query and logs a warning. If you expect instance-wide coverage and see that warning, use an administrator account instead. ### Checkpoint Management Checkpoints are stored **per project**, and each content type carries its own: * **Work items / merge requests** β€” the latest update timestamp seen, so the next run only asks GitLab for items changed since then * **Code repository** β€” the default branch's commit SHA at the end of the last successful walk, used as the base of the next comparison A checkpoint is only written after its stage succeeds. If a sync fails partway, the affected stage is simply repeated on the next run. *** ## 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 how much content your GitLab projects hold. A record is a single item β€” a work item, a merge request, a code file, or an attachment. | Approx record count | Estimated time | | ------------------- | ---------------------------------- | | Up to 10,000 | Under 10 minutes | | 10,000 to 50,000 | 10 to 30 minutes | | 50,000 to 100,000 | 30 to 60 minutes | | Over 100,000 | Roughly 1 hour per 100,000 records | As a rule of thumb, the connector syncs about **100,000 records per hour**. 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. Yes. On the **Configure Records** tab: * Use the **GitLab Groups** filter with the `In` operator to restrict the sync to selected groups and their subgroups, or `Not In` to exclude them * Use the **Repositories** filter the same way to target individual projects Narrowing scope here also speeds up sync, because excluded projects are never fetched at all. Both fields are live pickers that query your GitLab instance as you type. No. Code files are synced from each project's **default branch** only. Merge request diffs still capture the changes proposed from other branches, so review discussion remains searchable, but the file records themselves reflect the default branch. Yes. Set the **GitLab Instance URL** field to your host (for example `https://gitlab.mycompany.com`) when configuring authentication, and create the OAuth application on that instance rather than on gitlab.com. Leave the field blank for GitLab.com. ***

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.