Skip to main content

GitLab

Our integration with GitLab allows you to export GitLab objects to Port as entities of existing blueprints. The integration supports real-time event processing so Port always provides an accurate real-time representation of your GitLab resources.

💡 GitLab integration common use cases​

Our GitLab integration makes it easy to fill the software catalog with data directly from your GitLab organization, for example:

  • Map all of the resources in your GitLab organization, including groups, projects, monorepos, merge requests, issues, pipelines and other GitLab objects;
  • Watch for GitLab object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port;
  • Manage Port entities using GitOps;
  • etc.

Installation​

To install Port's GitLab integration, follow the installation guide.

Ingesting Git objects​

By using Port's GitLab integration, you can automatically ingest GitLab resources into Port based on real-time events.

Port's GitLab integration allows you to ingest a variety of objects resources provided by the GitLab API, including groups, projects, merge requests, pipelines and more. The GitLab integration allows you to perform extract, transform, load (ETL) on data from the GitLab API into the desired software catalog data model.

The GitLab integration uses a YAML configuration to describe the ETL process to load data into the developer portal. The approach reflects a golden middle between an overly opinionated Git visualization that might not work for everyone and a too-broad approach that could introduce unneeded complexity into the developer portal.

Here is an example snippet from the config which demonstrates the ETL process for getting merge-request data from GitLab and into the software catalog:

resources:
  # Extract
  - kind: merge-request
    selector:
      query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
    port:
      entity:
        mappings:
          # Transform & Load
          identifier: .id | tostring
          title: .title
          blueprint: '"gitlabMergeRequest"'
          properties:
            creator: .author.name
            status: .state
            createdAt: .created_at
            updatedAt: .updated_at
            link: .web_url

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

The integration configuration​

The integration configuration is how you specify the exact resources you want to query from your GitLab, and also how you specify which entities and which properties you want to fill with data from GitLab.

Here is an example for the integration configuration block:

resources:
  - kind: project
    selector:
      query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
    port:
      entity:
        mappings:
          identifier: .namespace.full_path | gsub("/";"-") # The Entity identifier will be the repository name.
          title: .name
          blueprint: '"service"'
          properties:
            url: .web_link
            description: .description
            namespace: .namespace.name
            fullPath: .namespace.full_path | split("/") | .[:-1] | join("/")
            defaultBranch: .default_branch

Integration configuration structure​

  • The root key of the integration configuration is the resources key:

    resources:
      - kind: project
        selector:
        ...

  • The kind key is a specifier for an object from the GitLab API:

      resources:
        - kind: project
          selector:
          ...
    Available GitLab resources

    The following resources can be used to map data from GitLab, it is possible to reference any field that appears in the API responses linked below for the GitLab integration mapping configuration.

Filtering unwanted objects​

The selector and the query keys let you filter exactly which objects from the specified kind will be ingested to the software catalog

resources:
  - kind: project
    selector:
      query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
    port:

For example, to ingest only repositories that have a name starting with "service", use the query key like this:

query: .name | startswith("service")

The port, entity and the mappings keys open the section used to map the GitLab API object fields to Port entities. To create multiple mappings of the same kind, you can add another item to the resources array;

resources:
  - kind: project
    selector:
      query: "true"
    port:
      entity:
        mappings: # Mappings between one GitLab API object to a Port entity. Each value is a JQ query.
          identifier: .namespace.full_path | gsub("/";"-")
          title: .name
          blueprint: '"service"'
          properties:
            url: .web_link
            description: .description
            namespace: .namespace.name
            fullPath: .namespace.full_path | split("/") | .[:-1] | join("/")
            defaultBranch: .default_branch
  - kind: project # In this instance project is mapped again with a different filter
    selector:
      query: '.name == "MyRepositoryName"'
    port:
      entity:
        mappings: ...
tip

Pay attention to the value of the blueprint key, if you want to use a hardcoded string, you need to encapsulate it in 2 sets of quotes, for example use a pair of single-quotes (') and then another pair of double-quotes (")

Permissions​

Port's GitLab integration requires a group access token with the api scope.

To create a group access token, follow the instructions in the installation guide

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.

Advanced​

Refer to the advanced page for advanced use cases and examples.