GitLab

In this example you are going to create a webhook integration between GitLab and Port, which will ingest merge request entities.

Prerequisites

Create the following blueprint definition and webhook configuration:

Merge request blueprint

{
  "identifier": "gitlabMergeRequest",
  "description": "This blueprint represents a Gitlab merge request in our software catalog",
  "title": "Gitlab Merge Request",
  "icon": "GitLab",
  "schema": {
    "properties": {
      "description": {
        "type": "string",
        "title": "Description"
      },
      "state": {
        "type": "string",
        "title": "State"
      },
      "mergeStatus": {
        "type": "string",
        "title": "Merge Status"
      },
      "lastChangeType": {
        "type": "string",
        "title": "Last Change Type",
        "description": "The type of the latest change made to this issue"
      },
      "repositoryUrl": {
        "type": "string",
        "title": "Repository URL",
        "format": "url"
      },
      "sourceBranch": {
        "type": "string",
        "title": "Source Branch"
      },
      "targetBranch": {
        "type": "string",
        "title": "Target Branch"
      },
      "mergeRequestUrl": {
        "type": "string",
        "format": "url",
        "title": "Merge Request URL"
      },
      "labels": {
        "type": "array",
        "title": "Labels"
      },
      "lastCommitUrl": {
        "type": "string",
        "format": "url",
        "title": "Last Commit URL"
      },
      "projectName": {
        "type": "string",
        "title": "Project name"
      },
      "projectUrl": {
        "type": "string",
        "format": "url",
        "title": "Project URL"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}

Pull request webhook configuration

{
  "identifier": "gitlabMapper",
  "title": "Gitlab mapper",
  "description": "A webhook configuration to map Gitlab merge requests to Port",
  "icon": "Gitlab",
  "mappings": [
    {
      "blueprint": "gitlabMergeRequest",
      "entity": {
        "identifier": ".body.object_attributes.id",
        "title": "(.body.object_attributes.id | tostring) + \" - \" + .body.object_attributes.title",
        "properties": {
          "state": ".body.object_attributes.state",
          "description": ".body.object_attributes.description",
          "mergeStatus": ".body.object_attributes.merge_status",
          "lastChangeType": ".body.object_attributes.action",
          "repositoryUrl": ".body.project.homepage",
          "sourceBranch": ".body.object_attributes.source_branch",
          "targetBranch": ".body.object_attributes.target_branch",
          "mergeRequestUrl": ".body.object_attributes.url",
          "lastCommitUrl": ".body.object_attributes.last_commit.url",
          "projectName": ".body.project.name",
          "projectUrl": ".body.project.homepage",
          "labels": ".body.object_attributes.labels"
        }
      }
    }
  ],
  "enabled": true,
  "security": {
    "requestIdentifierPath": ".headers.X-Gitlab-Event-Uuid"
  }
}

Create the GitLab webhook

tip

Webhooks can be created at the group level and at the project level, this example focuses on project-level webhooks

1. Go to your desired project in GitLab;
2. At the sidebar on the left side of the page select Settings and click on Webhooks;
3. Input the following details:
   1. URL - enter the value of the url key you received after creating the webhook configuration;
   2. Trigger - choose Merge request events;
   3. Be sure to keep the "Enable SSL verification" checkbox checked.
4. Click on Add webhook

tip

In order to view the different payloads and events available in GitLab webhooks, look here

Done! any change you make to a merge request (open, close, edit, etc.) will trigger a webhook event that GitLab will send to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly.