
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:
Splitting each project into four 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 confidential
work items or its source code.
What Gets Synced
Each connector instance syncs one project, chosen in the Repository filter. To sync more projects, add another connector instance for each one. For that project, the connector indexes the following content for AI-powered search:- Project: The selected project, and the groups and subgroups that contain it
- Code Files: Source files and folders on the branch chosen in the Branch filter, or the project’s default branch when no branch is chosen
- 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
Choose a connector
PipesHub has two GitLab connectors. This page covers both; the steps are the same unless a section says otherwise.Team connector: GitLab
Workspace settings → Connectors


Personal connector: GitLab Personal
Workspace settings → Personal → Your connectors


Because the redirect URLs differ, GitLab and GitLab Personal each need their own OAuth application
in GitLab.
Configuration Guide
Setup
Setup
Authentication Method
The GitLab connector offers two authentication methods. Pick one from the Authentication method dropdown on the Authenticate tab:GitLab Personal supports OAuth 2.0 only.Both methods accept the optional GitLab Instance URL for self-managed GitLab.
OAuth 2.0 provides secure, token-based access without requiring users to share their passwords.
Prerequisite: Email Visibility
This is not required for the user who set up the connector: PipesHub matches that user through their PipesHub account email. It also does not apply to GitLab Personal, which syncs no GitLab users.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
- Sign in to your GitLab account.
- Click on your Profile picture in the top right → Select “Edit profile”

- Select the “Profile” tab
- Scroll down to the “Public email” section
- Choose the email address to show on your public profile

- Click Update profile settings to save updated details
Generating Client ID and Secret
Step 1: Access GitLab Applications
- Navigate to GitLab applications: Go to user_settings/applications and sign in with your GitLab credentials.
- View Your Apps: You’ll see the “Applications” page where you can create and manage OAuth 2.0 applications.

Step 2: Create a New OAuth 2.0 Application
- Click the “Add new application” button in the top right corner
-
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 “Set up” (for GitLab Personal, use Workspace settings → Personal → Your connectors)
- Copy the Redirect/Callback URL shown in the configuration dialog. It ends in
connectors/oauth/callback/Gitlabfor GitLab, orconnectors/oauth/callback/GitLab%20Personalfor GitLab Personal:


- Select the following scopes:
read_userread_repositoryread_api
- Click “Save application” to proceed, a confirmation page will be shown with application details.

Step 3: Get OAuth Credentials
- Copy the following credentials:
- Application ID: Your app’s unique identifier
- Secret: Your app’s client secret
Step 4: Configure Connector in PipesHub
- 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 “Set up”)
-
With OAuth, the configuration dialog has three tabs (a personal access token skips Authorize):
- Authenticate - Enter an instance name and your credentials
- Authorize - Sign in to GitLab and grant access
- Configure records - Configure synchronization
- Enter an Instance name for this connector instance (required). Because each instance syncs one project, a name that includes the project makes instances easy to tell apart
- If an Authentication method dropdown is shown, choose OAuth 2.0
- Verify the Redirect/Callback URL displayed matches the callback URL you configured in GitLab Applications (Step 2)
-
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.comfor GitLab.com. For a self-managed or GitLab EE deployment, enter your host — for examplehttps://gitlab.mycompany.com


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.- Click “Next” to move forward
Step 5: Authorize the Connection
- On the Authorize tab, click Authenticate GitLab to proceed (Authenticate GitLab Personal to proceed for the personal connector)
- You’ll be redirected to GitLab’s authorization page

- Enter GitLab login credentials and click Sign In
- User will be shown the set of permissions needed, click Authorize to grant permissions

- You’ll be redirected back to PipesHub with a success message
- The connector status will update to show “Connected — you can continue to Configure records”

Using a personal access token
The GitLab connector can authenticate with a personal access token instead of OAuth 2.0. If you use a token, skip Steps 1–5 and do this instead:- In GitLab, open User settings → Access tokens (gitlab.com/-/user_settings/personal_access_tokens, or the same path on your self-managed host)
- Create a token with the same scopes the OAuth application uses:
read_user,read_repository, andread_api - Set an expiry date and copy the token
- In PipesHub, open Workspace settings → Connectors, find GitLab, and click Set up
- Enter an Instance name, and under Authentication method choose API Token
- Paste the token into Personal Access Token. For self-managed GitLab, also set the GitLab Instance URL
- Continue with Step 6 below
Step 6: Enable and Configure the Connector
- After successful authorization, click Continue to configuration → to open the Configure records tab
- A configuration dialog will appear with a section:
- Sync Settings - Configure synchronization strategy and schedule


Sync Settings
Configure your synchronization preferences:- Sync Strategy: Choose between “Scheduled” or “Manual”
- 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.

Indexing Filters
Indexing filters control what gets indexed for search from the content that was fetched.A file counts as a test file when it sits under a folder such as
test/, tests/, spec/,
__tests__/, __mocks__/, e2e/, testdata/, or fixtures/ (any capitalization), or when its
name follows a test convention such as test_*.py, *_test.go, *.test.ts, *.spec.js,
*Test.java, *_spec.rb, or conftest.py.

Save and Activate
- Click “Save configuration” to save your configuration.
- A dialog shows “Instance is configured and ready to sync!”. Choose Start syncing now, or I’ll do it later to start the sync from settings later
- The connector will verify credentials and begin initial synchronization
- Click the arrow on the connector card and check Records status to track sync completion
Supported Features
The GitLab connector syncs the following data from the project selected in the Repository filter (one project per connector instance):- Groups & Projects: The selected project and the groups and subgroups that contain it
- Code repository: Files and folders on the synced branch (the default branch unless you choose another in the Branch filter), 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
- OAuth 2.0 Documentation: api/oauth2
- GitLab REST API Documentation: gitlab/rest
Troubleshooting
Troubleshooting
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
- 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
- Verify you’re signing in with a valid GitLab account that has access to the required projects
- Verify the connector status shows “Active”
- Check that a project is selected in the Repository sync filter and that the authorizing account (or the token’s owner) can read it
- Review sync logs for specific error messages
- Disable and re-enable the connector to re-authenticate
- Check if the OAuth app is still active in GitLab applications
- If you use a personal access token, check its expiry date in GitLab and, if it has expired or been revoked, create a new one and update it in the connector
- Confirm Index Code Files is enabled under Indexing Filters
- Verify the OAuth application (or personal access token) includes the
read_repositoryscope — without it the connector can read issues and merge requests but not repository contents - Only one branch is synced: the one chosen in the Branch filter, or the default branch when none is chosen. If the chosen branch was deleted, code sync stops until you pick another
- Check that the files aren’t covered by the Exclude Paths filter or the built-in exclusions (see What is excluded from code sync)
- Test files are synced but not indexed unless Index Test Files is on
- Source and text files above 5 MB still appear as records, marked File Type Not Supported with the file’s size as the reason; their contents are not indexed (see How each file is indexed)
- 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 confidential work items, merge requests, or code. Planners (access level 15) also see confidential work items, but not merge requests or code
- 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
- 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
Connector Workflow
Synchronization Process
Synchronization Process
The GitLab connector follows a structured synchronization process to ensure all data is accurately synced and permissions are properly maintained.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.
Sync Overview
Every sync run executes the same ordered cycle: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
- A valid sync checkpoint exists
- Uses the saved sync checkpoint to fetch or filter for records updated since the last sync time
User Synchronization
- 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
- Member fetch: Retrieves group and project members with their access levels
- Email enrichment: Fetches each member’s full profile to read their public email, then matches it to a PipesHub account
Project Synchronization
- Project fetch: Retrieves the project selected in the Repository filter
- Container creation: The project becomes a record group with four children — Work items, Confidential work items, Merge requests, and Code repository. Parent GitLab groups are created above them
- Permission assignment: Member access levels are translated into per-container permissions (see Permission handling below)
Code Repository Synchronization
Code sync tracks the branch chosen in the Branch filter, or the project’s default branch when none is chosen, and is checkpointed on the branch’s current commit SHA. If the synced branch changes, the next sync walks the whole tree.Full sync (first run, or when the delta cannot be trusted):- Walks the entire repository tree, paginating through it
- Creates a folder record for each directory and a code file record for each file, with the file’s language detected from its path
- Prunes records for files that no longer exist in the tree
- Compares the checkpointed commit against the current branch head
- 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
- Applies deletions, renames, and upserts, then removes folders left empty
What is excluded from code sync
Not every file on the synced branch becomes a record. The connector skips content that adds noise without adding meaning, and never reads credential files. Excluded files get no record at all:A path the root
.gitattributes explicitly marks as not generated and not vendored (for example
-linguist-generated) is kept even if the built-in rules would skip it. Credential files, dot-files,
and Exclude Paths matches are always left out.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.How each file is indexed
The files that do become records are not all source code, so PipesHub reads each one with the reader that fits it:A file that isn’t indexed keeps its record and stays findable by name and path. It shows
File Type Not Supported, with a reason that says why:
- Above 5 MB: “This file is 12.5 MB, and PipesHub reads code and plain-text files up to 5 MB. Split it into smaller files, or ask your admin to raise the limit (CODE_FILE_MAX_SIZE_MB) and then choose Index all on the repository.”
- Minified or generator-marked files: “This is a generated file (a lock file, minified bundle, source map, test snapshot or a file its generator marked DO NOT EDIT), so PipesHub skips it to keep search results useful. Nothing needs fixing.”
- Git LFS pointers: “This file is stored with Git LFS, so the repository holds only a pointer to it, not its content. PipesHub skips the pointer. Nothing needs fixing.”
.ndjsonand.jsonl: “PipesHub can’t read .ndjson files yet. Convert the file to PDF, DOCX or TXT to make it searchable.”- Binary data: “This file holds binary data rather than text, so PipesHub can’t read it. If it is meant to be text, commit it as plain text (UTF-8) and the next sync will index it.”
On a self-hosted deployment, an admin can raise the 5 MB limit by setting the
CODE_FILE_MAX_SIZE_MB environment variable on the PipesHub container and restarting it. The
limit applies to source and plain-text files; CSV, JSON, and YAML files are not subject to it.Raising the limit doesn’t index the file by itself: a file marked File Type Not Supported
has no Reindex action, and a sync skips a repository that hasn’t changed. To index it, open the
project in PipesHub and choose Index all on its Code repository, which sends every file
in it back through indexing. Re-index failed, on the same menu, retries only files marked
Failed, so it leaves this file as it is.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)
- Fetch all work items and merge requests for the project (respecting full vs incremental sync rules above).
- Batch records for processing.
- Build BlockGroups for description and comments; map attachments and images to the description or the correct comment.
- For merge requests only, add blocks for commits, changed files with diffs, and review comments on changes.
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
This section applies to the GitLab connector. GitLab Personal syncs no memberships: everything it syncs is visible only to the user who set it up.Each project’s member list is read from GitLab and translated into per-user permissions. Because a project is split into four containers, a member’s GitLab access level decides which of them they can reach:Members with Minimal Access (access level 5) get no access in PipesHub. The author and the
assignees of a confidential work item can always see that item, whatever their role, as they can in
GitLab.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.
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 synced branch’s commit SHA at the end of the last successful walk, used as the base of the next comparison
FAQ
Queries not returning results. What could be wrong?
Queries not returning results. What could be wrong?
Common causes:
-
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.
-
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.
How long does the initial sync take?
How long does the initial sync take?
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.
As a rule of thumb, the connector syncs about 100,000 records per hour.
Why do I see no records after authenticating?
Why do I see no records after authenticating?
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.
Can I sync several projects, or a whole group?
Can I sync several projects, or a whole group?
Each connector instance syncs exactly one project, chosen in the required Repository filter
on the Configure records tab. To sync more projects, add another connector instance for each
one.The GitLab Groups filter only narrows the Repository picker to projects in the groups you
choose; it doesn’t sync a whole group. Both fields are live pickers that query your GitLab instance
as you type.
Does the connector sync all branches?
Does the connector sync all branches?
No. Code files are synced from one branch per project: the branch chosen in the Branch filter,
or the project’s default branch when none is chosen. Merge request diffs still capture the
changes proposed from other branches, so review discussion remains searchable, but the file records
themselves reflect the synced branch.
Does it work with self-managed GitLab?
Does it work with self-managed GitLab?
Yes. Set the GitLab Instance URL field to your host (for example
https://gitlab.mycompany.com) when configuring authentication, and create the OAuth application
(or personal access token) on that instance rather than on gitlab.com. Leave the field blank for
GitLab.com.