GitLab v2

Loading version...

Port's GitLab-v2 integration allows you to model GitLab resources in your software catalog and ingest data into them.

Supported resources GroupsProjectsIssuesMerge RequestsFilesFoldersMembersPipelinesJobs

GitLab v2 documentation

This page documents the latest GitLab integration, released in April 2025. For documentation of the previous integration, check out the GitLab page.

For users upgrading from the v1 integration, see the migration guide to learn how to migrate to the new GitLab-v2 integration.

Prerequisites

• A GitLab account with permissions to create access tokens.
• If you choose the real time & always on installation method, you will need a kubernetes cluster on which to install the integration.
• Your Port user role is set to Admin.

Configure access token

To allow Port to fetch data from your GitLab instance, you need to create an access token. Port supports two types of tokens for authentication: personal access tokens and group access tokens.

Personal access token (PAT)

A Personal Access Token (PAT) is suitable if you're the only one managing the integration and don't need frequent credential rotation. To create a personal access token see the GitLab personal access token guide.

• The token must belong to a user with access to the relevant GitLab resources (e.g., projects, groups).

Group access token

A Group Access Token is recommended when multiple team members manage the integration or when it's set up at the group level. To create a group access token, see the GitLab group access token guide.

• Create the token in a group that has access to the relevant projects.
• Set an appropriate expiration date and store it securely.

Service account token

A service account token is recommended where credentials must remain stable and unaffected by changes in human user membership.

To set up the account and generate a personal access token, see the GitLab service account guide.

• Add the service account to the relevant projects or groups with sufficient permissions (e.g., Developer or Maintainer).

Required scopes

The following scopes are required based on your usage.

• To enable real-time updates using webhooks, the token must include the api scope (required for managing webhooks).
• If you're not using realtime updates, the token needs read_api and read_repository scopes.

Setup

Choose your preferred installation method below. Not sure which to pick? See the installation methods overview.

Configuration

Port integrations use a YAML mapping block to ingest data from the third-party API into Port.

The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.

Default mapping configuration

This is the default mapping configuration for this integration:

Default mapping configuration (Click to expand)

deleteDependentEntities: true
createMissingRelatedEntities: true
resources:
- kind: project
  selector:
    query: 'true'
    includeLanguages: 'true'
    searchQueries:
      - name: hasPortConfig
        scope: blobs
        query: "filename:port.yml"
    includedFiles:
      - README.md
      - CODEOWNERS
  port:
    entity:
      mappings:
        identifier: .path_with_namespace | gsub(" "; "")
        title: .name
        blueprint: '"gitlabRepository"'
        properties:
          url: .web_url
          readme: .__includedFiles["README.md"]
          codeowners: .__includedFiles["CODEOWNERS"]
          language: .__languages // {} | to_entries | max_by(.value) | .key
          hasPortConfig: .__searchQueries["hasPortConfig"]
- kind: member
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .username
        title: .name
        blueprint: '"gitlabMember"'
        properties:
          url: .web_url
          state: .state
          email: .email
          locked: .locked
- kind: group-with-members
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .full_path
        title: .name
        blueprint: '"gitlabGroup"'
        properties:
          url: .web_url
          visibility: .visibility
          description: .description
        relations:
          gitlabMembers: .__members | map(.username)
- kind: merge-request
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id | tostring
        title: .title
        blueprint: '"gitlabMergeRequest"'
        properties:
          creator: .author.name
          status: .state
          createdAt: .created_at
          updatedAt: .updated_at
          mergedAt: .merged_at
          link: .web_url
          leadTimeHours: (.created_at as $createdAt | .merged_at as $mergedAt | ($createdAt | sub("\\..*Z$"; "Z") | strptime("%Y-%m-%dT%H:%M:%SZ") | mktime) as $createdTimestamp | ($mergedAt | if . == null then null else sub("\\..*Z$"; "Z") | strptime("%Y-%m-%dT%H:%M:%SZ") | mktime end) as $mergedTimestamp | if $mergedTimestamp == null then null else (((($mergedTimestamp - $createdTimestamp) / 3600) * 100 | floor) / 100) end)
          reviewers: .reviewers | map(.name)
        relations:
          project: .references.full // "" | gsub("!.+"; "")

Mapping & examples per resource

Use the explorer below to view the mapping and blueprint definition for each resource type. For additional resources and advanced configurations, see the examples page.

Monitoring and sync status

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.

Access control

The GitLab integration supports configurable access control to determine which resources are visible and accessible to the integration.

You can configure access control using the visibility configuration block in the integration mapping.

This allows you to filter resources based on GitLab access levels (Guest, Reporter, Developer, Maintainer, Owner). You can also disable access level filtering entirely to include all accessible resources.

Access control configuration

For detailed configuration options, access level reference, and practical examples, see the Advanced configuration section.

Capabilities

For detailed information about data ingestion capabilities, see the capabilities page.

Troubleshooting

Merge requests not appearing in catalog

If you can see your GitLab repositories in Port but merge requests are missing, this is likely due to insufficient group-level permissions.

Symptoms

• GitLab projects/repositories are visible in Port.
• Merge requests are missing from the catalog.
• No error messages in integration logs.

Root cause

The GitLab V2 integration fetches merge requests using group-level API queries. If your integration token only has access to individual projects (e.g., Developer or Maintainer role at the project level), it cannot access the group-level merge request data.

Solution

Ensure your integration token has access to the parent GitLab group that contains your projects:

• For Personal Access Tokens: The user must be a member of the group with at least Guest-level access.
• For Group Access Tokens: Create the token in the parent group with appropriate scopes.
• For Service Account Tokens: Add the service account to the group with at least Guest-level access.

Verification

To verify your token has the correct permissions:

• Test the token against GitLab's group API: GET /api/v4/groups/{group_id}/merge_requests.
• Ensure the token can list merge requests at the group level.
• Check that the group is accessible with your current token permissions.

Examples

Refer to the examples page for practical configurations and their corresponding blueprint definitions.

GitOps

Port's GitLab integration also provides GitOps capabilities, refer to the GitOps page to learn more.

Relevant Guides

For relevant guides and examples, see the guides section.