Examples
Mapping repositories, file contents and pull requests
In the following example you will ingest your Bitbucket projects, repositories, pull requests and files to Port. You will also see how to ingest folders from monorepo repositories and files from specific repositories:
Project blueprint
{
"identifier": "bitbucketProject",
"description": "A software catalog to represent Bitbucket project",
"title": "Bitbucket Project",
"icon": "BitBucket",
"schema": {
"properties": {
"private": {
"icon": "DefaultProperty",
"title": "Private",
"type": "boolean"
},
"description": {
"title": "Description",
"type": "string",
"icon": "DefaultProperty"
},
"type": {
"icon": "DefaultProperty",
"title": "Type",
"type": "string"
},
"url": {
"title": "Url",
"icon": "DefaultProperty",
"type": "string"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}
}
Repository blueprint
{
"identifier": "bitbucketRepository",
"title": "Repository",
"icon": "Microservice",
"schema": {
"properties": {
"readme": {
"title": "README",
"type": "string",
"format": "markdown"
},
"url": {
"title": "Repository URL",
"type": "string",
"format": "url"
},
"defaultBranch": {
"title": "Default branch",
"type": "string"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}
}
Pull request blueprint
{
"identifier": "bitbucketPullRequest",
"title": "Pull Request",
"icon": "GitVersion",
"schema": {
"properties": {
"creator": {
"title": "Creator",
"type": "string",
"format": "user"
},
"assignees": {
"title": "Assignees",
"type": "array"
},
"reviewers": {
"title": "Reviewers",
"type": "array"
},
"status": {
"title": "Status",
"type": "string",
"enum": ["MERGED","OPEN","DECLINED"],
"enumColors": {
"MERGED": "purple",
"OPEN": "green",
"DECLINED": "red"
}
},
"createdAt": {
"title": "Created At",
"type": "string",
"format": "date-time"
},
"updatedAt": {
"title": "Updated At",
"type": "string",
"format": "date-time"
},
"link": {
"title": "Link",
"format": "url",
"type": "string"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {
"lead_time_days": {
"title": "Lead time (Days)",
"calculation": "if .properties.status == \"MERGED\" then ((.properties.updatedAt | sub(\"\\\\.[0-9]+\\\\+00:00$\"; \"Z\") | strptime(\"%Y-%m-%dT%H:%M:%SZ\") | mktime) - (.properties.createdAt | sub(\"\\\\.[0-9]+\\\\+00:00$\"; \"Z\") | strptime(\"%Y-%m-%dT%H:%M:%SZ\") | mktime)) / 86400 | tonumber else null end",
"type": "number"
}
},
"aggregationProperties": {},
"relations": {
"repository": {
"title": "Repository",
"target": "bitbucketRepository",
"required": false,
"many": false
}
}
}
Port port-app-config.yml
resources:
- kind: project
selector:
query: "true"
port:
entity:
mappings:
identifier: '.uuid | gsub("[{-}]"; "")'
title: ".name"
blueprint: '"bitbucketProject"'
properties:
private: .is_private
description: ".description"
type: .type
url: ".links.html.href"
- kind: repository
selector:
query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
port:
entity:
mappings:
identifier: ".name" # The Entity identifier will be the repository name. After the Entity is created, the exporter will send `PATCH` requests to update this microservice within Port.
title: ".name"
blueprint: '"bitbucketRepository"'
properties:
readme: file://README.md # fetching the README.md file that is within the root folder of the repository and ingesting its contents as a markdown property
url: ".links.html.href"
defaultBranch: .main_branch
relations:
project: '.project.uuid | gsub("[{-}]"; "")'
- kind: pull-request
selector:
query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
port:
entity:
mappings:
identifier: ".destination.repository.name + (.id|tostring)" # The Entity identifier will be the repository name + the pull request ID. After the Entity is created, the exporter will send `PATCH` requests to update this pull request within Port.
title: ".title"
blueprint: '"bitbucketPullRequest"'
properties:
creator: ".author.display_name"
assignees: "[.participants[].user.display_name]"
reviewers: "[.reviewers[].user.display_name]"
status: ".state"
createdAt: ".created_on"
updatedAt: ".updated_on"
link: ".links.html.href"
relations:
repository: ".destination.repository.name"
tip
- Refer to the installation guide to learn more about the
port-app-config.ymlinstallation process; - We leverage JQ JSON processor to map and transform Bitbucket objects to Port Entities;
- Click Here for the Bitbucket project object structure.
- Click Here for the Bitbucket repository object structure.
- Click Here for the Bitbucket pull request object structure.
After creating the blueprints and updating the mapping, you will see new entities in Port matching your repositories alongside their README.md file contents and pull requests.
Mapping repositories and monorepos
In the following example you will ingest your Bitbucket repositories and their folders to Port. By following this example you can map your different repositories, packages and libraries from your monorepo into separate entities in Port:
Repository blueprint
{
"identifier": "bitbucketRepository",
"title": "Repository",
"icon": "Microservice",
"schema": {
"properties": {
"readme": {
"title": "README",
"type": "string",
"format": "markdown"
},
"url": {
"title": "Repository URL",
"type": "string",
"format": "url"
},
"defaultBranch": {
"title": "Default branch",
"type": "string"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}
}
Port port-app-config.yml
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: integrations/* # Relative path to the folders within the repositories.
repos: # List of repositories to include folders from.
- name: port-repo-3 # the name of the repository to include folders from.
branch: new # Optional; branch name to map the folders from, defaults to the repository's default branch.
- path: integrations/**/*
repos:
- name: port-repo-3
port:
entity:
mappings:
identifier: .folder.path
title: .folder.path | split("/") | last
blueprint: '"bitbucketRepository"'
properties:
url: >-
.repo.links.html.href + "/src/" + .repo.mainbranch.name + "/" +
.folder.path
defaultBranch: .repo.mainbranch.name
readme: file://README.md
tip
Mapping files
In the following example you will ingest files from a specific repository. You will be able to map files and and file contents from specific repositories as entities in Port:
File blueprint
{
"identifier": "file",
"title": "File",
"icon": "Bitbucket",
"schema": {
"properties": {
"path": {
"title": "Path",
"type": "string",
"icon": "DefaultProperty",
"description": "The path of the file in the repository"
},
"content": {
"title": "Content",
"type": "string",
"icon": "DefaultProperty",
"description": "The content of the file"
},
"link": {
"title": "Link",
"type": "string",
"format": "url",
"icon": "Link",
"description": "Link to the file in Bitbucket"
},
"required": ["path"]
},
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {},
"relations": {
"repository": {
"title": "Repository",
"target": "bitbucketRepository",
"required": true,
"many": false
}
}
}
Port port-app-config.yml
resources:
- kind: file
selector:
query: 'true'
files:
path: integrations/bitbucket-cloud/ #Absolute path to the file to sync from the repository; The more specific the path the better;
filenames: #Required; List of files to sync from the repository in the given path;
- README.md #Just the filename, no wildcards;
- port.yaml #Just the filename, no wildcards;
repo: #Optional; List of repositories to include files from. If not provided, all repositories will be included;
- port-repo-3
skipParsing: true #Optional; If true, the file will not be parsed by Port;
port:
entity:
mappings:
identifier: .metadata.path
blueprint: '"file"'
properties:
content: .content
path: .metadata.path
link: .repo.links.html.href + "/src/" + .branch + "/" + .metadata.path
relations:
repository: .repo.name
tip
Mapping supported resources
The above examples show specific use cases, but Port's Bitbucket integration supports other use cases as well. To adapt the examples shown above, use the Bitbucket API reference to learn about the available fields for the different supported objects:
When adding the ingestion of other resources, remember to add a entry to the resources array and change the value provided to the kind key accordingly.