Advanced

The GitLab integration supports additional flags to provide extra configuration options, making it easier to customize its behavior to suit your needs.

To use the advanced configuration and additional flags, let's add them as root keys to our integration configuration.
For example, here's how we can add the createMissingRelatedEntities flag:

createMissingRelatedEntities: false
resources:
  - kind: merge-request
    selector:
      query: "true"
    port:
      entity:
        mappings:
        ... mappings configuration

Using advanced configurations

Let's look at the advanced configuration parameters we can add to the integration configuration:

Delete dependent entities

The deleteDependentEntities parameter is used to enable deletion of dependent Port entities. This is useful when you have two blueprints with a required relation, and the target entity in the relation should be deleted. In this scenario, the delete operation will fail if this flag is set to false if the flag is set to true, the source entity will be deleted as well.

• Default value: false (disabled).
• Use case: Enable this flag if dependent entities should be deleted when the target entity is deleted.

Enable merge entity

With the enableMergeEntity parameter, you can specify whether to use the create/update or create/override strategy when creating entities listed in a port.yml file.

• Default value: false (uses create/override).
• Use case: Set to true to allow external sources to update some properties while GitLab remains the source of truth for others.

Create missing related entities

The createMissingRelatedEntities parameter enables automatic creation of placeholder entities in Port when they're referenced in relationships but don't yet exist in your software catalog.

• Default value: true to allow the GitLab app to create barebones related entities, in case those related entities do not exist in the software catalog.
• Use case: use false if you do not want this default behavior (do not create missing related entities).

Access control

The visibility configuration allows you to control which GitLab resources are accessible to the integration based on access levels.

Access levels

GitLab uses numeric access levels to define permissions:

Level	Role	Description
10	Guest	Read-only access to public resources
20	Reporter	Can view and download code
30	Developer	Can push code and manage issues
40	Maintainer	Can manage project settings
50	Owner	Full administrative access

Parameters

• useMinAccessLevel: Boolean flag to enable/disable access level filtering

  • Default value: true
  • Use case: Set to false to include all accessible resources without filtering

• minAccessLevel: Integer specifying the minimal required access level

  • Default value: 30 (Developer)
  • Use case: Restrict integration to resources where the token has the specified access level or higher

Configuration examples

# Only sync owned projects
visibility:
  useMinAccessLevel: true
  minAccessLevel: 50
resources:
  - kind: project
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .path_with_namespace | gsub(" "; "")
          title: .name
          blueprint: '"service"'

# Include all accessible resources
visibility:
  useMinAccessLevel: false
resources:
  - kind: project
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .path_with_namespace | gsub(" "; "")
          title: .name
          blueprint: '"service"'