Examples

Mapping projects, file contents and merge requests

In the following example you will ingest your GitLab projects, their README.md file contents and merge requests to Port, you may use the following Port blueprint definitions and integration configuration:

Repository blueprint

{
  "identifier": "repository",
  "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": {}
}

Merge request blueprint

{
  "identifier": "mergeRequest",
  "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": "Create At",
        "type": "string",
        "format": "date-time"
      },
      "updatedAt": {
        "title": "Updated At",
        "type": "string",
        "format": "date-time"
      },
      "description": {
        "title": "Description",
        "type": "string",
        "format": "markdown"
      },
      "link": {
        "title": "Link",
        "format": "url",
        "type": "string"
      }
    }
  },
  "relations": {
    "repository": {
      "target": "repository",
      "required": false,
      "many": false
    }
  }
}

Ocean integration configuration

resources:
  - kind: project
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .path_with_namespace | gsub(" "; "")
          title: .name
          blueprint: '"repository"'
          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
  - kind: merge-request
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .title
          blueprint: '"mergeRequest"'
          properties:
            creator: .author.name
            status: .state
            createdAt: .created_at
            updatedAt: .updated_at
            description: .description
            link: .web_url
          relations:
            repository: .references.full | gsub("!.+"; "")

tip

• 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 projects, pipelines and jobs

In the following example you will ingest your GitLab projects, their pipelines and jobs runs to Port, you may use the following Port blueprint definitions and integration configuration:

Repository blueprint

{
  "identifier": "repository",
  "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": {}
}

Pipeline blueprint

{
  "identifier": "pipeline",
  "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": {
      "target": "repository",
      "type": "Repository",
      "required": true,
      "many": false
    }
  }
}

Job blueprint

{
  "identifier": "job",
  "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": "pipeline",
      "required": false,
      "many": false
    }
  }
}

Ocean integration configuration

resources:
  - kind: project
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .path_with_namespace | gsub(" "; "")
          title: .name
          blueprint: '"repository"'
          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: '"pipeline"'
          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: '"job"'
          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

tip

• 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

In the following example you will ingest your GitLab projects and their monorepo folders to Port, you may use the following Port blueprint definitions and integration configuration:

Repository blueprint

{
  "identifier": "repository",
  "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": {}
}

Ocean integration configuration

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: '"project"'
          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

tip

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

tip

You can also specify 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

tip

• 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

In the following example you will ingest your GitLab projects and their folders to Port, you may use the following Port blueprint definitions and integration configuration:

Repository blueprint

{
  "identifier": "repository",
  "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": {}
}

Folder blueprint

{
  "identifier": "folder",
  "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": "repository",
      "required": false,
      "many": false
    }
  }
}

Port port-app-config.yml

resources:
  - kind: repository
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .name
          title: .name
          blueprint: '"repository"'
          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: '"folder"'
          properties:
            url: >-
              .repo.web_url + "/tree/" + .repo.default_branch  + "/" +
              .folder.path
            readme: file://README.md
          relations:
            repository: .repo.name

tip

• 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

In the following example you will ingest your GitLab projects and their issues to Port, you may use the following Port blueprint definitions and integration configuration:

Repository blueprint

{
  "identifier": "repository",
  "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": {}
}

Issue blueprint

{
  "identifier": "issue",
  "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"
        }
      }
    }
  },
  "relations": {
    "repository": {
      "target": "repository",
      "title": "Repository",
      "required": true,
      "many": false
    }
  }
}

Ocean integration configuration

resources:
  - kind: project
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .path_with_namespace | gsub(" "; "")
          title: .name
          blueprint: '"repository"'
          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: '"issue"'
          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("#.+"; "")

tip

• 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 supported resources

The above examples shows a 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.

• project
• merge-request
• pipeline
• job
• issue

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.