Advanced Analytica Advanced Analytica: IBOM
← All connectors
Gitlab logo

Source connector

Gitlab

Set up Gitlab as a source and move its data into your chosen destination.

Version 4.6.0 certified generally available

GitLab

Use this guide to set up the GitLab source connector and find reference information.

Prerequisites

  • A GitLab account on GitLab.com or a self-hosted GitLab instance using the v4 API

For Airbyte Cloud:

For Airbyte Open Source:

Setup guide

Step 1: Set up GitLab

Create a GitLab account or set up a self-hosted GitLab instance.

If you use a personal access token, generate one in Settings > Access Tokens with the read_api scope. The read_api scope provides read-only API access. This includes all groups, projects, the container registry and the package registry.

Step 2: Set up the connector

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. In the left navigation bar, click Sources. Then click + new source in the top-right corner.
  3. On the source setup page, select GitLab from the Source type dropdown. Enter a name for this connector.
  4. Click Authenticate your GitLab account and select OAuth or Personal Access Token for authentication.
  5. Log in and authorise the GitLab account.
  6. API URL (Optional) - Enter your self-hosted GitLab instance’s host, or use gitlab.com (default).
  7. Start date (Optional) - Enter the date to start replicating stream data, using the YYYY-MM-DDT00:00:00Z format.
  8. Groups (Optional) - Enter a list of GitLab group paths, such as airbytehq for one group.
  9. Projects (Optional) - Enter a list of GitLab project paths, such as airbytehq/airbyte.
  10. Number of Concurrent Threads (Optional) - Set the number of concurrent threads used for syncing. Higher values can speed up syncs but may reach rate limits. The default is 4, and the allowed range is 2 to 25. Adjust this value for your GitLab instance’s rate limits.
  11. Click Set up source.

For Airbyte Open Source:

  1. Go to the Airbyte UI and click Sources > + New source.
  2. Select GitLab and enter a name for the connector.
  3. Authenticate with a Personal Access Token.
  4. API URL (Optional) - Enter your self-hosted GitLab instance’s host, or use gitlab.com (default).
  5. Start date (Optional) - Enter the date to start replicating stream data, using the YYYY-MM-DDT00:00:00Z format.
  6. Groups (Optional) - Enter a list of GitLab group paths, such as airbytehq for one group.
  7. Projects (Optional) - Enter a list of GitLab project paths, such as airbytehq/airbyte.
  8. Number of Concurrent Threads (Optional) - Set the number of concurrent threads used for syncing. Higher values can speed up syncs but may reach rate limits. The default is 4, and the allowed range is 2 to 25. Adjust this value for your GitLab instance’s rate limits.
  9. Click Set up source.

Choose groups and projects

Groups and Projects control how much data you sync. Almost every stream is scoped to a group or project.

  • Leave both blank to discover every group your token can see and sync their projects.
  • Set Groups to sync those groups, their descendant groups and their projects.
  • Set both to use Projects as a filter for projects discovered from your groups. If nothing matches, the connector syncs the project paths in Projects directly. This fallback lets you sync a project outside the listed groups.

Use full paths instead of display names or numeric IDs. Use airbytehq for a group and airbytehq/airbyte for a project.

API URL format

Enter a host in API URL, not a full API endpoint. The connector adds /api/v4/. Therefore, gitlab.company.org and https://gitlab.company.org both work. A value containing a path, such as gitlab.company.org/api/v4, fails validation. Only the http and https schemes are accepted. Airbyte Cloud rejects http.

Supported sync modes

The GitLab source connector supports these sync modes:

Supported streams

The connector outputs these streams:

Limitations

API version

The connector uses GitLab API v4. It works with GitLab.com and self-hosted GitLab instances.

Incremental sync window

Most incremental streams request data in 180-day windows. A first sync of a long-lived project can therefore issue many requests. Deployments and group and project milestones aren’t windowed. They filter on updated_at using updated_after and updated_before. They ignore Start date to read all history. merge_request_commits reads commits for merge requests returned by the incremental merge_requests query. commits filters on created_at using GitLab’s since and until parameters. If Start date is blank, other incremental streams start from 2014-01-01. For most projects, this effectively includes all history. Set a start date to shorten the initial sync.

Incremental deployments and milestones

Deployments and milestones filter on updated_at through updated_after and updated_before. They ignore Start date, so Full Refresh output remains unchanged. Deployments are requested with order_by=updated_at. Boundary records may be read again. Use Incremental | Append + Deduped to avoid duplicates.

Incremental merge request commits

The connector only reads commits for merge requests returned by the incremental merge_requests query. It uses merge_request_updated_at as the cursor. It won’t pick up commit changes that don’t update the parent merge request’s updated_at.

Incremental pipeline child streams

jobs, pipelines_extended and pipeline_trigger_jobs each make one request per pipeline. In Incremental mode, these requests only cover pipelines returned by the incremental pipelines query. These pipelines have an updated_at at or after the previous sync’s cursor. All three streams use pipeline_updated_at as their cursor. This value is the pipeline’s updated_at returned by pipelines. Keep these points in mind:

  • The connector won’t pick up changes that don’t update the parent pipeline’s updated_at. Examples include erasing a job or job artefacts expiring. Use Full Refresh for these streams if you need those changes.
  • When you retry a job, GitLab creates an attempt under a new job id. The jobs stream returns every attempt, including earlier attempts of retried jobs. A pipeline can therefore contain several rows with the same name. To keep only each job’s latest attempt, retain the highest id for each pipeline_id and name. Deleted pipelines and their jobs aren’t removed from the destination.
  • In pipeline_trigger_jobs, downstream_pipeline fields such as status reflect the downstream pipeline when the upstream pipeline last changed. A trigger job without strategy: depend finishes when the downstream pipeline is created. Later downstream status changes don’t update the upstream pipeline, so the connector doesn’t read the row again. For the current downstream status, join downstream_pipeline_id to the pipelines stream. Alternatively, use Full Refresh for pipeline_trigger_jobs.
  • The cursor has one-second precision, and GitLab’s updated_after filter includes the boundary. Each sync requests the latest updated regular and child pipeline in each project again. This means up to two pipelines per project. Use Incremental | Append + Deduped to avoid duplicate rows.
  • A project first appearing after the initial incremental sync doesn’t start from Start date. It starts from the latest pipelines cursor, minus the previous sync’s duration. This applies to projects added to the connector configuration. It also applies to projects created in or moved into a configured group. The connector doesn’t read older pipelines in that project. Refresh these streams to backfill them.
  • Changing a stream’s sync mode clears its saved state. After switching from Full Refresh, the first Incremental sync reads every pipeline from Start date. With Incremental | Append, earlier Full Refresh rows remain in the destination. Use Append + Deduped or clear the stream when you switch.
  • In Full Refresh mode, a failed attempt can resume without reading every pipeline again. The destination must support refreshes. You must also refresh the schema after upgrading to 4.5.0. This behaviour also covers existing Full Refresh connections that never switch to Incremental. An attempt resumes from each project’s last completed 180-day pipelines window. Some pipelines are therefore read twice. Use Full Refresh | Overwrite + Deduped to avoid duplicate rows. Each new Full Refresh sync still starts from Start date.
  • Pipelines use page-number pagination. A pipeline updated during pagination can shift another pipeline to an earlier page. The connector might then miss that pipeline. Its child records remain skipped until the pipeline is updated again.

Child pipelines on large instances

Since version 4.4.41, pipelines reads each project twice. It reads once for regular pipelines and once with source=parent_pipeline for child pipelines. Existing connections retain their per-project cursor for regular pipelines. They automatically backfill child pipelines from Start date.

The backfill isn’t guaranteed when the stream tracks more than 10,000 partitions. This is roughly 5,000 projects because each project now has two partitions. Above this limit, the connector stores one shared cursor for the whole stream. It doesn’t read child pipelines older than that cursor. For a connection this large, reset four streams once after upgrading: pipelines, pipelines_extended, jobs and pipeline_trigger_jobs. This reset loads historical child pipelines.

Rate limits

The connector respects per-endpoint rate limits based on GitLab.com’s documented defaults. This covers Groups API, Members API, Projects API and general authenticated traffic:

EndpointRate limit
GET /groups200 requests/min
GET /groups/:id400 requests/min
GET /groups/:id/descendant_groups200 requests/min
GET /projects/:id400 requests/min
GET /groups/:id/members/all200 requests/min
GET /projects/:id/members/all200 requests/min
All other authenticated requests2,000 requests/min

From October 19, 2026, GitLab.com also applies subscription-tier rate limits. Free namespaces allow 5,000 requests hourly and 100 requests per minute for each user. Premium and Ultimate follow in January 2027. See rate limits on GitLab.com. Syncs may pause for long periods while the connector waits for these limits to reset.

Administrators may configure different rate limits for self-hosted GitLab instances. The connector also reads the RateLimit-Remaining and RateLimit-Reset response headers. When GitLab returns HTTP 429, the connector waits for the period in Retry-After, up to about one hour. It then retries. If the header is missing, the connector retries with exponential backoff. If rate limit errors persist, create an issue.

Adjust Number of Concurrent Threads to control the connector’s number of parallel requests. Lower this value if other integrations share your API quota or you experience rate limiting.

API error handling

ResponseBehavior
401 UnauthorizedThe sync fails with Unable to refresh the access_token, please re-authenticate in Sources > Settings. Re-authenticate the source, or replace an expired or revoked personal access token.
403 ForbiddenThe connector skips the group, project, or resource and continues. Nothing fails, so partial data is the only symptom.
404 Not FoundThe sync fails with Groups and/or projects that you provide are invalid or you don't have permission to view it. Check the paths in Groups and Projects for typos and confirm your token can see them.
500 Internal Server ErrorRetried.

The connector silently skips 403 responses. Missing data therefore usually indicates a permissions gap, not a bug. Check that your token can access every expected group and project.

Connection checks read the groups endpoint. A check can succeed while individual project streams return no data. This happens when the token can list groups but can’t read their projects.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
4.6.02026-10-1689052Add incremental sync support to the deployments, group_milestones, project_milestones, and merge_request_commits streams
4.5.72026-11-0390577Update dependencies
4.5.62026-10-2789911Update dependencies
4.5.52026-10-2288981Normalize epics due_date_from_milestones and start_date_from_milestones from datetime strings to YYYY-MM-DD dates (typed date columns are unchanged; raw JSON values change); add work_item_id, imported and imported_from to the epics schema
4.5.42026-10-2089088Include earlier attempts of retried jobs in the jobs stream
4.5.32026-10-2089217Update dependencies
4.5.22026-10-1388467Honor GitLab Retry-After headers for HTTP 429 rate limits and raise heartbeat timeout to 90 minutes
4.5.12026-10-1388629Update dependencies
4.5.02026-10-0787655Add incremental sync support to the pipelines_extended, jobs, and pipeline_trigger_jobs streams. Failed Full Refresh attempts of these streams can now resume, which can write duplicate rows under Full Refresh | Overwrite
4.4.432026-10-0687865Update dependencies
4.4.422026-09-2987138Update dependencies
4.4.412026-09-2486933Include child pipelines in the pipelines stream (and therefore pipelines_extended and jobs) and add the pipeline_trigger_jobs stream
4.4.402026-09-2286599Update dependencies
4.4.392026-09-1586063Update dependencies
4.4.382026-09-0885485Update dependencies
4.4.372026-08-1884568Update dependencies
4.4.362026-08-1183941Update dependencies
4.4.352026-07-2882903Update dependencies
4.4.342026-07-2182429Update dependencies
4.4.332026-07-1481830Update dependencies
4.4.322026-06-3081041Update dependencies
4.4.312026-06-2380476Update dependencies
4.4.302026-06-1777516Lower default concurrency from 8 to 4; set HTTPAPIBudget to documented GitLab.com rate limits
4.4.292026-06-1679874Update dependencies
4.4.282026-06-0979295Update dependencies
4.4.272026-06-0278724Update dependencies
4.4.262026-04-2877265Update dependencies
4.4.252026-04-2176608Update dependencies
4.4.242026-04-1376276Rename “concurrent workers” to “concurrent threads” in connector spec
4.4.232026-04-1076210Promote 4.4.23-rc.5 to GA: HTTPAPIBudget with concurrency 8
4.4.23-rc.52026-04-0175994Revert concurrency to 8 with HTTPAPIBudget for progressive rollout tuning
4.4.23-rc.42026-03-3175915Re-enable HTTPAPIBudget with concurrency 10 for rate limit protection during progressive rollout
4.4.23-rc.32026-03-2775537Increase default concurrency from 8 to 10 for progressive rollout tuning
4.4.23-rc.22026-03-2575480Comment out HTTPAPIBudget to isolate concurrency tuning during progressive rollout
4.4.23-rc.12026-03-0970858Add HTTPAPIBudget and concurrency_level for improved sync performance
4.4.222026-02-2473774Update dependencies
4.4.212026-02-1773401Update dependencies
4.4.202026-02-1071398Update dependencies
4.4.192026-02-0572262Update CDK version from 7.6.1 to 7.6.5
4.4.182025-12-1870698Update dependencies
4.4.172025-12-1170839Change check stream from projects to groups to fix timeout for large GitLab organizations
4.4.162025-11-2569875Update dependencies
4.4.152025-11-1869411Update dependencies
4.4.142025-10-2969030Update dependencies
4.4.132025-10-2168297Update dependencies
4.4.122025-10-1468000Update dependencies
4.4.112025-10-0767266Update dependencies
4.4.102025-09-3066076Update dependencies
4.4.92025-09-1065997Update dependencies
4.4.82025-08-2665556Update dependencies
4.4.72025-08-2365362Update dependencies
4.4.62025-08-0964579Update dependencies
4.4.52025-08-0264222Update dependencies
4.4.42025-07-2663913Update dependencies
4.4.32025-07-1963489Update dependencies
4.4.22025-07-1863309Adds type property to config_normalization_rules in manifest
4.4.12025-07-1261471Update dependencies
4.4.02025-07-0762831Promoting release candidate 4.4.0-rc.1 to a main version.
4.4.0-rc.12025-07-0262480Migrate to manifest-only
4.3.72025-06-0257264Update dependencies
4.3.62025-03-2954945Update dependencies
4.3.52025-02-2351695Update dependencies
4.3.42025-01-1544671Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
4.3.32024-08-1844207Update dependencies
4.3.22024-08-1243856Update dependencies
4.3.12024-08-0443058Update dependencies
4.3.02024-07-3142920Migrate to CDK v4.1.0
4.2.22024-07-2842601Update dependencies
4.2.12024-07-2142295Update dependencies
4.2.02024-07-1742085Migrate to CDK v2.4.0
4.1.02024-07-1742021Migrate to CDK v1.8.0
4.0.82024-07-1441835Update dependencies
4.0.72024-07-1141470Update dependencies
4.0.62024-07-1041100Update dependencies
4.0.52024-07-0740894Update dependencies
4.0.42024-06-2640417Update dependencies
4.0.32024-06-2340102Update dependencies
4.0.22024-05-0736637Schema descriptions and CDK 0.80.0
4.0.12024-04-2337505Set error code 500 as retryable
4.0.02024-04-0135989Migrate to low-code
3.0.02024-02-1534548Fix merge_request_commits stream to return commits for each merge request
2.1.22024-02-1335167Manage dependencies with Poetry.
2.1.12024-01-1634203prepare for airbyte-lib
2.1.02024-01-0933676Add fields to Commits (extended_trailers), Groups (emails_enabled, service_access_tokens_expiration_enforced) and Projects (code_suggestions, model_registry_access_level) streams
2.0.02023-10-2631700Add correct date-time format for Deployments, Projects and Groups Members streams
1.8.42023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
1.8.32023-10-1831547Add validation for invalid groups_list and/or projects_list
1.8.22023-10-1731492Expand list of possible error status codes when handling expired access_token
1.8.12023-10-1231375Mark start_date as optional, migrate groups and projects to array
1.8.02023-10-1231339Add undeclared fields to streams schemas, validate date/date-time format in stream schemas
1.7.12023-10-1031210Added expired access_token handling, while checking the connection
1.7.02023-08-0829203Add Deployments stream
1.6.02023-06-3027869Add shared_runners_setting field to groups
1.5.12023-06-2427679Fix formatting
1.5.02023-06-1527392Make API URL an optional parameter in spec.
1.4.22023-06-1527346Partially revert changes made in version 1.0.4, disallow http calls in cloud.
1.4.12023-06-1327351Fix OAuth token expiry date.
1.4.02023-06-1227234Skip stream slices on 403/404 errors, do not fail syncs.
1.3.12023-06-0827147Improve connectivity check for connections with no projects/groups
1.3.02023-06-0827150Update stream schemas
1.2.12023-06-0226947New field name added to Pipelines and PipelinesExtended stream schema
1.2.02023-05-1722293Preserve data in records with flattened keys
1.1.12023-05-2326422Fix error 404 Repository Not Found when syncing project with Repository feature disabled
1.1.02023-05-1025948Introduce two new fields in the Projects stream schema
1.0.42023-04-2021373Accept api_url with or without scheme
1.0.32023-02-1422992Specified date formatting in specification
1.0.22023-01-2722001Set AvailabilityStrategy for streams explicitly to None
1.0.12023-01-2321713Fix missing data issue
1.0.02022-12-057506Add OAuth2.0 authentication option
0.1.122022-12-1520542Revert HttpAvailability changes, run on cdk 0.15.0
0.1.112022-12-1420479Use HttpAvailabilityStrategy + add unit tests
0.1.102022-12-1220384Fetch groups along with their subgroups
0.1.92022-12-1120348Fix 403 error when syncing EpicIssues stream
0.1.82022-12-0220023Fix duplicated records issue for Projects stream
0.1.72022-12-0119986Fix GroupMilestones stream schema
0.1.62022-06-2313252Add GroupIssueBoards stream
0.1.52022-05-0211907Fix null projects param and container_expiration_policy
0.1.42022-03-2311140Ingest All Accessible Groups if not Specified in Config
0.1.32021-12-218991Update connector fields title/description
0.1.22021-10-187108Allow all domains to be used as api_url
0.1.12021-10-126932Fix pattern field in spec file, remove unused fields from config files, use cache from CDK
0.1.02021-07-064174Initial Release
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.