Skip to main content

Check out Port for yourself 

Examples

Mapping projects, README.md and merge requests​

The following example demonstrates how to ingest your GitLab projects, their README.md file contents and merge requests to Port.
You can use the following Port blueprint definitions and integration configuration:

Repository blueprint
{
  "identifier": "gitlabRepository",
  "title": "Repository",
  "icon": "Microservice",
  "schema": {
    "properties": {
      "url": {
        "title": "URL",
        "type": "string",
        "format": "url"
      },
      "readme": {
        "title": "README",
        "type": "string",
        "format": "markdown"
      },
      "description": {
        "title": "Description",
        "type": "string"
      },
      "language": {
        "title": "Language",
        "type": "string"
      },
      "namespace": {
        "title": "Namespace",
        "type": "string"
      },
      "fullPath": {
        "title": "Full Path",
        "type": "string"
      },
      "defaultBranch": {
        "title": "Default Branch",
        "type": "string"
      },
      "labels": {
        "items": {
          "type": "object"
        },
        "type": "array",
        "title": "Labels"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}
Merge request blueprint
{
  "identifier": "gitlabMergeRequest",
  "title": "Merge Request",
  "icon": "GitVersion",
  "schema": {
    "properties": {
      "creator": {
        "title": "Creator",
        "type": "string"
      },
      "status": {
        "title": "Status",
        "type": "string",
        "enum": [
          "opened",
          "closed",
          "merged",
          "locked"
        ],
        "enumColors": {
          "opened": "yellow",
          "closed": "red",
          "merged": "green",
          "locked": "blue"
        }
      },
      "createdAt": {
        "title": "Created At",
        "type": "string",
        "format": "date-time"
      },
      "updatedAt": {
        "title": "Updated At",
        "type": "string",
        "format": "date-time"
      },
      "mergedAt": {
        "title": "Merged At",
        "type": "string",
        "format": "date-time"
      },
      "link": {
        "title": "Link",
        "format": "url",
        "type": "string"
      },
      "leadTimeHours": {
        "title": "Lead Time in hours",
        "type": "number"
      },
      "reviewers": {
        "title": "Reviewers",
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "repository": {
      "title": "Repository",
      "target": "gitlabRepository",
      "required": false,
      "many": false
    }
  }
}
Integration mapping 
resources:
  - kind: project
    selector:
      query: "true"
      includeLabels: "true"
    port:
      entity:
        mappings:
          identifier: .path_with_namespace | gsub(" "; "")
          title: .name
          blueprint: '"gitlabRepository"'
          properties:
            url: .web_url
            readme: file://README.md
            description: .description
            language: .__languages | to_entries | max_by(.value) | .key
            namespace: .namespace.name
            fullPath: .namespace.full_path
            defaultBranch: .default_branch
            labels: .__labels
  - 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:
            repository: .references.full | gsub("!.+"; "")
Learn more
  • Refer to the setup section to learn more about the integration configuration setup process.
  • We leverage JQ JSON processor to map and transform GitLab objects to Port entities.
  • Click Here for the GitLab project object structure.
  • Click Here for the GitLab merge request object structure.

After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your projects alongside their README.md file contents and merge requests.

Mapping files and file contents​

The following example shows how to ingest dependencies from a package.json file in your GitLab repository into Port.
You can use the following Port blueprint definitions and integration configuration:

Package blueprint
{
  "identifier": "package",
  "title": "Package",
  "icon": "Package",
  "schema": {
    "properties": {
      "package": {
        "icon": "DefaultProperty",
        "type": "string",
        "title": "Package"
      },
      "version": {
        "icon": "DefaultProperty",
        "type": "string",
        "title": "Version"
      }
    },
    "required": [
      "package",
      "version"
    ]
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}
Integration mapping
resources:
  - kind: file
    selector:
      query: 'true'
      files:
        path: '**/package.json'
        repos:
          # The repository NAME should be used here, not the URL slug, e.g. "Repo Name" not "repo-name"
          - MyRepoName
    port:
      itemsToParse: .file.content.dependencies | to_entries
      entity:
        mappings:
          identifier: >-
            .item.key + "_" + if (.item.value | startswith("^")) then
            .item.value[1:] else .item.value end
          title: .item.key + "@" + .item.value
          blueprint: '"package"'
          properties:
            package: .item.key
            version: .item.value
          relations: {}

The example will parse the package.json file in your repository and extract the dependencies into Port entities.
For more information about ingesting files and file contents, click here

Mapping Groups, Subgroups and Projects​

The following example demonstrates how to ingest your GitLab groups, subgroups and projects to Port.
You can use the following Port blueprint definitions and integration configuration:

Group blueprint
{
  "identifier": "gitlabGroup",
  "title": "Group",
  "icon": "GitLab",
  "schema": {
    "properties": {
      "visibility": {
        "icon": "Lock",
        "title": "Visibility",
        "type": "string",
        "enum": [
          "public",
          "internal",
          "private"
        ],
        "enumColors": {
          "public": "red",
          "internal": "yellow",
          "private": "green"
        }
      },
      "url": {
        "title": "URL",
        "format": "url",
        "type": "string",
        "icon": "Link"
      },
      "description": {
        "title": "Description",
        "type": "string",
        "icon": "BlankPage"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}
Repository blueprint
{
  "identifier": "gitlabRepository",
  "title": "Repository",
  "icon": "Microservice",
  "schema": {
    "properties": {
      "url": {
        "title": "URL",
        "type": "string",
        "format": "url"
      },
      "readme": {
        "title": "README",
        "type": "string",
        "format": "markdown"
      },
      "description": {
        "title": "Description",
        "type": "string"
      },
      "language": {
        "title": "Language",
        "type": "string"
      },
      "namespace": {
        "title": "Namespace",
        "type": "string"
      },
      "fullPath": {
        "title": "Full Path",
        "type": "string"
      },
      "defaultBranch": {
        "title": "Default Branch",
        "type": "string"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "group": {
      "title": "Group",
      "target": "gitlabGroup",
      "required": true,
      "many": false
    }
  }
}
Integration mapping 
deleteDependentEntities: true
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
  - kind: group
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .full_path
          title: .name
          blueprint: '"gitlabGroup"'
          properties:
            url: .web_url
            visibility: .visibility
            description: .description
  - kind: project
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .path_with_namespace | gsub(" "; "")
          title: .name
          blueprint: '"gitlabRepository"'
          properties:
            url: .web_url
            readme: file://README.md
            description: .description
            language: .__languages | to_entries | max_by(.value) | .key
            namespace: .namespace.name
            fullPath: .namespace.full_path
            defaultBranch: .default_branch
          relations:
            group: >-
              .path_with_namespace | gsub(" "; "") | split("/") | .[:-1] |
              join("/")
Learn more
  • Refer to the setup section to learn more about the integration configuration setup process.
  • We leverage JQ JSON processor to map and transform GitLab objects to Port entities.
  • Click Here for the GitLab project object structure.
  • Click Here for the GitLab subgroup object structure.

Mapping projects, pipelines and jobs​

The following example demonstrates how to ingest your GitLab projects, their pipelines and jobs runs to Port.
You can use the following Port blueprint definitions and integration configuration:

Repository blueprint
{
  "identifier": "gitlabRepository",
  "title": "Repository",
  "icon": "Microservice",
  "schema": {
    "properties": {
      "url": {
        "title": "URL",
        "type": "string",
        "format": "url"
      },
      "readme": {
        "title": "README",
        "type": "string",
        "format": "markdown"
      },
      "description": {
        "title": "Description",
        "type": "string"
      },
      "language": {
        "title": "Language",
        "type": "string"
      },
      "namespace": {
        "title": "Namespace",
        "type": "string"
      },
      "fullPath": {
        "title": "Full Path",
        "type": "string"
      },
      "defaultBranch": {
        "title": "Default Branch",
        "type": "string"
      },
      "labels": {
        "items": {
          "type": "object"
        },
        "type": "array",
        "title": "Labels"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}
Pipeline blueprint
{
  "identifier": "gitlabPipeline",
  "title": "Pipeline",
  "icon": "GitLab",
  "schema": {
    "properties": {
      "createdAt": {
        "title": "Created At",
        "type": "string",
        "format": "date-time"
      },
      "updatedAt": {
        "title": "Updated At",
        "type": "string",
        "format": "date-time"
      },
      "creator": {
        "title": "Creator",
        "type": "string"
      },
      "status": {
        "title": "Status",
        "type": "string",
        "enum": [
          "created",
          "waiting_for_resource",
          "preparing",
          "pending",
          "running",
          "success",
          "failed",
          "canceled",
          "skipped",
          "manual",
          "scheduled"
        ],
        "enumColors": {
          "created": "yellow",
          "waiting_for_resource": "yellow",
          "preparing": "yellow",
          "pending": "yellow",
          "running": "yellow",
          "success": "green",
          "failed": "red",
          "canceled": "red",
          "skipped": "red",
          "manual": "blue",
          "scheduled": "blue"
        }
      },
      "stages": {
        "title": "Stages",
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "link": {
        "title": "Link",
        "type": "string",
        "format": "url"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "repository": {
      "title": "Repository",
      "target": "gitlabRepository",
      "required": true,
      "many": false
    }
  }
}
Job blueprint
{
  "identifier": "gitlabJob",
  "title": "Job",
  "icon": "GitLab",
  "schema": {
    "properties": {
      "createdAt": {
        "title": "Created At",
        "type": "string",
        "format": "date-time"
      },
      "startedAt": {
        "title": "Started At",
        "type": "string",
        "format": "date-time"
      },
      "finishedAt": {
        "title": "Finished At",
        "type": "string",
        "format": "date-time"
      },
      "creator": {
        "title": "Creator",
        "type": "string"
      },
      "stage": {
        "title": "Stage",
        "type": "string"
      },
      "status": {
        "title": "Status",
        "type": "string",
        "enum": [
          "failed",
          "warning",
          "pending",
          "running",
          "manual",
          "scheduled",
          "canceled",
          "success",
          "skipped",
          "created"
        ],
        "enumColors": {
          "failed": "red",
          "warning": "red",
          "pending": "yellow",
          "running": "yellow",
          "manual": "blue",
          "scheduled": "blue",
          "canceled": "red",
          "success": "green",
          "skipped": "red",
          "created": "yellow"
        }
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "pipeline": {
      "target": "gitlabPipeline",
      "required": false,
      "many": false
    }
  }
}
Integration mapping 
resources:
  - kind: project
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .path_with_namespace | gsub(" "; "")
          title: .name
          blueprint: '"gitlabRepository"'
          properties:
            url: .web_url
            description: .description
            language: .__languages | to_entries | max_by(.value) | .key
            namespace: .namespace.name
            fullPath: .namespace.full_path
            defaultBranch: .default_branch
  - kind: pipeline
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .title // (.id | tostring)
          blueprint: '"gitlabPipeline"'
          properties:
            creator: .user.name
            status: .status
            createdAt: .created_at
            updatedAt: .updated_at
            description: .description
            link: .web_url
          relations:
            repository: .__project.path_with_namespace | gsub(" "; "")
  - kind: job
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .name
          blueprint: '"gitlabJob"'
          properties:
            creator: .user.name
            startedAt: .started_at
            updatedAt: .updated_at
            finishedAt: .finished_at
            stage: .stage
            status: .status
            link: .web_url
          relations:
            pipeline: .pipeline.id | tostring
Learn more
  • Refer to the setup section to learn more about the integration configuration setup process.
  • We leverage JQ JSON processor to map and transform GitLab objects to Port entities.
  • Click Here for the GitLab project object structure.
  • Click Here for the GitLab pipeline object structure.
  • Click Here for the GitLab job object structure.

After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your projects alongside their pipelines and jobs.

Mapping projects and monorepos​

The following example demonstrates how to ingest your GitLab projects and their monorepo folders to Port.
You can use the following Port blueprint definitions and integration configuration:

Repository blueprint
{
  "identifier": "gitlabRepository",
  "title": "Repository",
  "icon": "Microservice",
  "schema": {
    "properties": {
      "url": {
        "title": "URL",
        "type": "string",
        "format": "url"
      },
      "readme": {
        "title": "README",
        "type": "string",
        "format": "markdown"
      },
      "description": {
        "title": "Description",
        "type": "string"
      },
      "language": {
        "title": "Language",
        "type": "string"
      },
      "namespace": {
        "title": "Namespace",
        "type": "string"
      },
      "fullPath": {
        "title": "Full Path",
        "type": "string"
      },
      "defaultBranch": {
        "title": "Default Branch",
        "type": "string"
      },
      "labels": {
        "items": {
          "type": "object"
        },
        "type": "array",
        "title": "Labels"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}
Integration mapping 
resources:
  - kind: folder
    selector:
      query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
      folders: # Specify the repositories and folders to include under this relative path.
        - path: "apps/" # Relative path to the folders within the repositories.
          repos: # List of repositories to include folders from.
            - backend-service
            - frontend-service
    port:
      entity:
        mappings:
          identifier: .folder.name
          title: .folder.name
          blueprint: '"gitlabProject"'
          properties:
            url: >-
              .repo.web_url + "/tree/" + .repo.default_branch  + "/" +
              .folder.path
            description: .repo.description
            namespace: .repo.namespace.name
            full_path: .repo.path_with_namespace + "/" + .folder.path
            language: .repo.__languages | to_entries | max_by(.value) | .key
            readme: file://README.md

To retrieve the root folders of your monorepo, you can use this following syntax in your port-app-config.yml:

- kind: folder
  selector:
    query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
    folders: # Specify the repositories and folders to include under this relative path.
      - path: "/" # Relative path to the folders within the repositories
        repos: # List of repositories to include folders from.
          - backend-service
          - frontend-service

You can also specify a different path for each monorepo repository, for example:

- kind: folder
  selector:
    query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
    folders: # Specify the repositories and folders to include under this relative path.
      - path: "apps/"
        repos:
          - gaming-apps
      - path: "microservices/"
        repos:
          - backend-services
Learn more
  • Refer to the setup section to learn more about the integration configuration setup process.
  • We leverage JQ JSON processor to map and transform GitLab objects to Port entities.
  • Click Here for the GitLab project object structure.
  • Click Here for the GitLab repository tree object structure.

Mapping projects and folders​

The following example demonstrates how to ingest your GitLab projects and their folders to Port.
You can use the following Port blueprint definitions and integration configuration:

Repository blueprint
{
  "identifier": "gitlabRepository",
  "title": "Repository",
  "icon": "Microservice",
  "schema": {
    "properties": {
      "url": {
        "title": "URL",
        "type": "string",
        "format": "url"
      },
      "readme": {
        "title": "README",
        "type": "string",
        "format": "markdown"
      },
      "description": {
        "title": "Description",
        "type": "string"
      },
      "language": {
        "title": "Language",
        "type": "string"
      },
      "namespace": {
        "title": "Namespace",
        "type": "string"
      },
      "fullPath": {
        "title": "Full Path",
        "type": "string"
      },
      "defaultBranch": {
        "title": "Default Branch",
        "type": "string"
      },
      "labels": {
        "items": {
          "type": "object"
        },
        "type": "array",
        "title": "Labels"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}
Folder blueprint
{
  "identifier": "gitlabFolder",
  "title": "Folder",
  "icon": "Gitlab",
  "schema": {
    "properties": {
      "readme": {
        "title": "README",
        "type": "string",
        "format": "markdown"
      },
      "url": {
        "title": "Folder URL",
        "type": "string",
        "format": "url"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "repository": {
      "title": "Repository",
      "target": "gitlabRepository",
      "required": false,
      "many": false
    }
  }
}
Port port-app-config.yml 
resources:
  - kind: repository
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .name
          title: .name
          blueprint: '"gitlabRepository"'
          properties:
            readme: file://README.md
            url: .web_url
            defaultBranch: .default_branch
  - kind: folder
    selector:
      query: "true"
      folders:
        - path: "/" # Using "/" will ingest the folders from the root of each of repository as entities
          repos: # Add any repositories you want to map folders from to the following list
            - backend-service
            - frontend-service
    port:
      entity:
        mappings:
          identifier: .folder.name
          title: .folder.name
          blueprint: '"gitlabFolder"'
          properties:
            url: >-
              .repo.web_url + "/tree/" + .repo.default_branch  + "/" +
              .folder.path
            readme: file://README.md
          relations:
            repository: .repo.name
Learn more
  • Refer to the setup section to learn more about the integration configuration setup process.
  • We leverage JQ JSON processor to map and transform GitLab objects to Port entities.
  • Click Here for the GitLab project object structure.
  • Click Here for the GitLab repository tree object structure.

Mapping projects and issues​

The following example demonstrates how to ingest your GitLab projects and their issues to Port.
You can use the following Port blueprint definitions and integration configuration:

Repository blueprint
{
  "identifier": "gitlabRepository",
  "title": "Repository",
  "icon": "Microservice",
  "schema": {
    "properties": {
      "url": {
        "title": "URL",
        "type": "string",
        "format": "url"
      },
      "readme": {
        "title": "README",
        "type": "string",
        "format": "markdown"
      },
      "description": {
        "title": "Description",
        "type": "string"
      },
      "language": {
        "title": "Language",
        "type": "string"
      },
      "namespace": {
        "title": "Namespace",
        "type": "string"
      },
      "fullPath": {
        "title": "Full Path",
        "type": "string"
      },
      "defaultBranch": {
        "title": "Default Branch",
        "type": "string"
      },
      "labels": {
        "items": {
          "type": "object"
        },
        "type": "array",
        "title": "Labels"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}
Issue blueprint
{
  "identifier": "gitlabIssue",
  "title": "Issue",
  "icon": "GitLab",
  "schema": {
    "properties": {
      "link": {
        "title": "Link",
        "type": "string",
        "format": "url"
      },
      "description": {
        "title": "Description",
        "type": "string",
        "format": "markdown"
      },
      "createdAt": {
        "title": "Created At",
        "type": "string",
        "format": "date-time"
      },
      "closedAt": {
        "title": "Closed At",
        "type": "string",
        "format": "date-time"
      },
      "updatedAt": {
        "title": "Updated At",
        "type": "string",
        "format": "date-time"
      },
      "creator": {
        "title": "Creator",
        "type": "string"
      },
      "status": {
        "title": "Status",
        "type": "string",
        "enum": ["opened", "closed"],
        "enumColors": {
          "opened": "green",
          "closed": "purple"
        }
      },
      "labels": {
        "title": "Labels",
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "calculationProperties": {},
  "relations": {
    "repository": {
      "title": "Repository",
      "target": "gitlabRepository",
      "required": true,
      "many": false
    }
  }
}
Integration mapping 
resources:
  - kind: project
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .path_with_namespace | gsub(" "; "")
          title: .name
          blueprint: '"gitlabRepository"'
          properties:
            url: .web_url
            description: .description
            language: .__languages | to_entries | max_by(.value) | .key
            namespace: .namespace.name
            fullPath: .namespace.full_path
            defaultBranch: .default_branch
  - kind: issue
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .title
          blueprint: '"gitlabIssue"'
          properties:
            creator: .author.name
            status: .state
            createdAt: .created_at
            closedAt: .closed_at
            updatedAt: .updated_at
            description: .description
            link: .web_url
            labels: "[.labels[]]"
          relations:
            repository: .references.full | gsub("#.+"; "")
Learn more
  • Refer to the setup section to learn more about the integration configuration setup process.
  • We leverage JQ JSON processor to map and transform GitLab objects to Port entities.
  • Click Here for the GitLab project object structure.
  • Click Here for the GitLab issue object structure.

After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your projects alongside their issues.

Mapping group or project and members​

The following example demonstrates how to ingest your GitLab members to Port.
You can use the following Port blueprint definitions and integration configuration:

Prerequisites​

  • When using GitLab Self Hosted, an admin token is required, rather than a group access token, to retrieve the primary email addresses of members.
  • When using GitLab Enterprise, accounts can retrieve the primary email addresses of members within their groups, provided the members are part of user accounts administered by an organization with verified domains for groups. For more information, see limitations.
GitLab free plan limitation

Primary email addresses are not available for GitLab "Free plan" users.

Member blueprint
  {
    "identifier": "gitlabMember",
    "title": "Member",
    "icon": "GitLab",
    "schema": {
      "properties": {
        "email": {
          "type": "string",
          "title": "Email",
          "description": "GitLab primary email address.",
          "icon": "User",
          "format": "user"
        },
        "link": {
          "icon": "Link",
          "type": "string",
          "title": "Link",
          "format": "url",
          "description": "URL link to the GitLab member."
        },
        "state": {
          "title": "State",
          "type": "string",
          "icon": "GitLab",
          "description": "The current state of the GitLab member (e.g., active)."
        },
        "locked": {
          "type": "string",
          "title": "Locked",
          "icon": "GitLab",
          "description": "Indicates if the GitLab member is locked."
        }
      },
      "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "aggregationProperties": {},
    "relations": {}
  }
Integration mapping 
resources:
  - kind: group-with-members # replace with `project-with-members` to retrieve members from projects
    selector:
      query: 'true'
      includeVerboseMemberObject: 'true'
    port:
      itemsToParse: .__members
      entity:
        mappings:
          identifier: .item.username
          title: .item.name
          blueprint: '"gitlabMember"'
          properties:
            link: .item.web_url
            state: .item.state
            email: .item.email
            locked: .item.locked

GitLab allows the creation of tokens (bots) for automated tasks, which can be associated with groups or projects via access tokens. The includeBotMembers parameter is used to filter out bot members from the actual GitLab members. By default, this selector is set to false, which means the integration will only sync actual members.

  - kind: group-with-members
    selector:
      query: 'true'
      includeBotMembers: false
  - kind: project-with-members
    selector:
      query: 'true'
      includeBotMembers: false

Mapping members and groups​

The following example demonstrates how to ingest your GitLab groups and their members to Port.
You can use the following Port blueprint definitions and integration configuration:

Group blueprint
 {
    "identifier": "gitlabGroup",
    "title": "Group",
    "icon": "GitLab",
    "schema": {
      "properties": {
        "visibility": {
          "icon": "Lock",
          "title": "Visibility",
          "type": "string",
          "description": "Visibility status of the group. (e.g public, internal etc. )",
          "enum": [
            "public",
            "internal",
            "private"
          ],
          "enumColors": {
            "public": "red",
            "internal": "yellow",
            "private": "green"
          }
        },
        "url": {
          "title": "URL",
          "format": "url",
          "type": "string",
          "icon": "Link",
          "description": "Link to the gitlab group"
        },
        "description": {
          "title": "Description",
          "type": "string",
          "icon": "BlankPage",
          "description": "A short description of the gitlab group"
        }
      },
      "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "aggregationProperties": {},
    "relations": {
      "gitlabMembers": {
        "title": "Gitlab Members",
        "target": "gitlabMember",
        "required": false,
        "many": true
      }
    }
  }
Integration mapping 
resources:
  - kind: group-with-members
    selector:
      query: 'true'
      includeVerboseMemberObject: 'true'
    port:
      itemsToParse: .__members
      entity:
        mappings:
          identifier: .item.username
          title: .item.name
          blueprint: '"gitlabMember"'
          properties:
            link: .item.web_url
            state: .item.state
            email: .item.email
            locked: .item.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)

Mapping members and projects​

The following example demonstrates how to ingest your GitLab projects and their members to Port.
You can use the following Port blueprint definitions and integration configuration:

Limitation

Real time webhook events are not supported for the project-with-members kind.

Repository blueprint
{
  "identifier": "gitlabRepository",
  "title": "Repository",
  "icon": "Microservice",
  "schema": {
    "properties": {
      "url": {
        "title": "URL",
        "type": "string",
        "format": "url"
      },
      "readme": {
        "title": "README",
        "type": "string",
        "format": "markdown"
      },
      "description": {
        "title": "Description",
        "type": "string"
      },
      "language": {
        "title": "Language",
        "type": "string"
      },
      "namespace": {
        "title": "Namespace",
        "type": "string"
      },
      "fullPath": {
        "title": "Full Path",
        "type": "string"
      },
      "defaultBranch": {
        "title": "Default Branch",
        "type": "string"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "gitlabMembers": {
      "title": "Gitlab Members",
      "target": "gitlabMember",
      "required": false,
      "many": true
    }
  }
}
Integration mapping 
resources:
  - kind: project-with-members
    selector:
      query: 'true'
      includeVerboseMemberObject: 'true'
    port:
      itemsToParse: .__members
      entity:
        mappings:
          identifier: .item.username
          title: .item.name
          blueprint: '"gitlabMember"'
          properties:
            link: .item.web_url
            state: .item.state
            email: .item.email
            locked: .item.locked
  - kind: project-with-members
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .path_with_namespace | gsub(" "; "")
          title: .name
          blueprint: '"gitlabRepository"'
          properties:
            url: .web_url
            readme: file://README.md
            description: .description
            language: .__languages | to_entries | max_by(.value) | .key
            namespace: .namespace.name
            fullPath: .namespace.full_path
            defaultBranch: .default_branch
          relations:
            gitlabMembers: .__members | map(.username)
Learn more
  • Refer to the setup section to learn more about the integration configuration setup process.
  • We leverage JQ JSON processor to map and transform GitLab objects to Port entities.
  • Click Here for the GitLab project or group member object structure.

Mapping supported resources​

The examples above show specific use cases, but Port's GitLab integration supports the ingestion of many other GitLab objects. To adapt the examples above, use the GitLab API reference to learn about the available fields for the different supported objects:

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.

When adding the ingestion of other resources, remember to add an entry to the resources array and change the value provided to the kind key accordingly.

After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your projects alongside their issues.