GitLab | Alephant Documentation

What it indexes

The GitLab connector targets one project identified by Project Owner and Project Name. It does not provide an all-groups or multi-project mode in the current Admin form.

GitLab data	Indexing behavior
Merge requests	When enabled, each MR becomes one document. Its title is the identifier and its description is the searchable text. State, type, author, creation time, and update time are retained. Comments, approvals, diffs, and commit contents are not indexed.
Issues and work items	When enabled, each returned issue becomes one document. Its title is the identifier and its description is the searchable text. State, returned type, author, creation time, and update time are retained. Comments are not indexed.
Repository files	Repository-file indexing is controlled by the deployment-level `GITLAB_CONNECTOR_INCLUDE_CODE_FILES`, not by the Admin form, and is disabled unless that value is `true`. When enabled, the connector traverses the current default branch and attempts to index every blob that does not match its built-in path exclusions. README files and source code are included; this is broader than GitHub’s document-only policy.
Branches and links	There is no branch selector. File content and blob links use the project’s current default branch. Merge requests and issues are project-wide and are not filtered by branch.
File decoding	File bytes are decoded as UTF-8 and then Latin-1 on a Unicode decode failure. There is no connector-level extension allowlist or file-size gate in this implementation, so enabling code files requires testing binary, generated, vendored, and large-file behavior in the target project.

The connector does not create separate documents for project metadata, commits, wiki pages, pipelines, releases, snippets, or repository directories.

Prerequisites

Identify the exact GitLab root URL, such as https://gitlab.com or the HTTPS root of a self-managed instance.
Create a dedicated GitLab access token that can open the target project and read the enabled merge-request, issue, repository-tree, and file APIs.
Current connector credentials contain a GitLab URL and one access-token field. They do not contain application ID, application secret, OAuth callback, or private-key fields; do not enter an application secret in the token field.
Record the exact project owner namespace and project name. The current form creates one connector for one project.
Allow the OpenCore worker to reach the GitLab host and allow user browsers to reach the same host to open source links.
Ask the deployment operator whether GITLAB_CONNECTOR_INCLUDE_CODE_FILES is enabled. Treat it as a deployment-wide content decision rather than a per-connector checkbox.

Credentials

Method	OpenCore credential values	Authentication behavior
GitLab access token	`gitlab_url: <GITLAB_URL>`, `gitlab_access_token: <GITLAB_ACCESS_TOKEN>`	OpenCore initializes the GitLab API client at the configured URL and passes the token as its private token. The same credential reads all selected content.

Use the GitLab instance root URL, not a project page. The current schema does not expose a separate GitLab application or OAuth credential flow. Exact scope labels depend on the token type and GitLab deployment; verify access to the actual project APIs used by the enabled content types.

Configure in OpenCore

In the Admin panel, open Connectors, select GitLab, and create a credential with the GitLab root URL and access token.
Enter the exact Project Owner namespace and Project Name for one project.
Under advanced settings, enable or disable Include MRs and Include Issues. These options control descriptions only; they do not add comments, diffs, or commit contents.
Confirm the deployment-level code-file setting with the operator. The connector page has no per-project code-file control, branch selector, extension filter, or size limit.
Choose OpenCore Private groups for restricted project content. Use Public only when every OpenCore account may search every MR, issue, and file emitted by this connector.
Set refresh and cleanup options, create the connector, and run an indexing attempt.

The standard Admin-created connector uses poll (input_type: poll): GitLab is not included in the Admin isLoadState list. The Admin form does not expose a full/load control. Each standard indexing attempt therefore calls the connector’s poll path with a time window rather than its separate load_from_state method.

During a poll, merge requests are requested in descending update order and are filtered to the poll start and end. When an MR older than the poll start is encountered, the current implementation returns from the entire polling pass; if MRs and issues are both enabled, the issue stage can therefore be skipped. When the issue stage is reached, issues are filtered by update time, but the current API call does not explicitly request update ordering and also returns at the first item older than the start. Test incremental coverage against the target GitLab version and content mix.

When code-file indexing is enabled, every poll traverses and emits the current default-branch file set before MR and issue filtering. File documents receive the ingestion time as their update time; the poll window is not used to skip unchanged repository files.

Permissions

The GitLab token determines which project content OpenCore can ingest, but this connector does not synchronize GitLab project membership, groups, roles, protected-branch rules, confidential-issue access, or per-item permissions into OpenCore. GitLab is not offered as an Auto Sync Permissions source in the current Admin access selector.

Search access is therefore controlled only by the connector’s OpenCore Private groups or Public mode. Any user with connector access can search all MR descriptions, issue descriptions, author identifiers, and enabled default-branch file contents emitted by the token, even if that user cannot open the source item in GitLab.

Use a least-privilege token, one connector per project, and separate OpenCore Private groups for audiences that must not share content. Do not rely on a GitLab confidential flag, project role, protected branch, or source group to hide a document after it has been indexed.

Verify

Run the connector and confirm the credential resolves the intended GitLab host and exact owner/project path.
Search for one enabled MR title and distinctive description, and one enabled issue or work-item title and description.
Confirm MR comments, approvals, diffs, issue comments, and commit contents are absent.
If code-file indexing is disabled, confirm README and source files are absent. If it is enabled, search a README and a source file from the default branch, then confirm a file that exists only on another branch is absent.
Compare a known set of source issues with an incremental poll. First include MRs and observe whether an older MR prevents the issue stage; then disable MRs in a diagnostic connector to isolate the issue loop. Include issues with mixed update times and compare every expected ID. Disabling MRs removes only the MR-stage early return and does not guarantee complete incremental issue coverage.
If code files are enabled, run two polls without repository changes and confirm the operational cost and repeated file upserts are acceptable. Test representative binary, generated, vendored, and large files.
Test every assigned OpenCore group and a user outside those groups because GitLab access is not re-evaluated at search time.

Troubleshooting

Symptom	What to check
Authentication fails	Replace the invalid or expired GitLab access token and confirm it belongs to the configured host.
Project is not found or access is denied	Check the root GitLab URL, exact owner namespace, exact project name, token project access, and network reachability.
Only one project indexes	This is expected. The connector accepts one owner/project pair; create separate connectors and OpenCore access groups for additional projects.
Merge requests or issues are empty	Confirm the corresponding advanced checkbox is enabled, the token can read that API, and the connector state filter includes the expected items. Only descriptions are searchable.
An incrementally updated issue is missed	With MRs enabled, an old MR can end the poll before issues run. Disabling MRs is only a diagnostic way to isolate that first early return: the issue call still lacks explicit update ordering and returns at the first old issue, so running the issue loop on its own does not guarantee completeness. The standard Admin path has no full/load control. For strict completeness, reconcile expected issue IDs against GitLab and treat gaps as an implementation limitation until the polling logic is fixed.
README or source files are missing	Confirm `GITLAB_CONNECTOR_INCLUDE_CODE_FILES` is exactly enabled at deployment level and that the file is on the current default branch and not matched by a built-in exclusion. There is no Admin checkbox for this setting.
File links point to an unexpected branch	The connector always reads the current project default branch. Change the GitLab project default or use a different ingestion path; this connector has no branch override.
File polling is unexpectedly expensive	With code indexing enabled, every poll walks and emits the default-branch file set regardless of the MR/issue poll window. Reduce refresh frequency, narrow the project, or disable the deployment-level code-file setting.
Binary or generated content appears as text	Code-file mode has no extension or size allowlist and falls back to Latin-1 decoding. Disable the deployment setting if the project’s file mix is not safe for broad traversal.
Users can search content they cannot open in GitLab	This is expected because GitLab source permissions are not synchronized. Restrict the connector with OpenCore Private groups, reduce token/project scope, or separate projects into connectors.