Examples
Mapping repositories, file contents and pull requests
In the following example you will ingest your Bitbucket repositories, their README.md file contents and pull requests to Port, you may use the following Port blueprint definitions and port-app-config.yml:
Service blueprint
{
"identifier": "service",
"title": "Service",
"icon": "Microservice",
"schema": {
"properties": {
"readme": {
"title": "README",
"type": "string",
"format": "markdown"
},
"url": {
"title": "Service 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": {
"service": {
"title": "Service",
"target": "service",
"required": false,
"many": false
}
}
}
Port port-app-config.yml
resources:
- 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 service (repository) name. After the Entity is created, the exporter will send `PATCH` requests to update this microservice within Port.
title: ".name"
blueprint: '"service"'
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
- 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:
service: ".destination.repository.name"
- Refer to the setup section to learn more about the
port-app-config.ymlsetup process; - We leverage JQ JSON processor to map and transform Bitbucket objects to Port Entities;
- Click Here for the Bitbucket repository object structure.
- Click Here for the Bitbucket pull request object structure.
After creating the blueprints and committing the port-app-config.yml file to your .bitbucket-private or to a specific repository, you will see new entities in Port matching your repositories alongside their README.md file contents and pull requests. (Remember that the port-app-config.yml file has to be in the default branch of the repository to take effect).
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 services, packages and libraries from your monorepo into separate entities in Port. you may use the following Port blueprint definitions and port-app-config.yml:
Service blueprint
{
"identifier": "service",
"title": "Service",
"icon": "Microservice",
"schema": {
"properties": {
"readme": {
"title": "README",
"type": "string",
"format": "markdown"
},
"url": {
"title": "Service 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: 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
blueprint: '"service"'
properties:
url: .repo.links.html.href + "/src/" + .repo.mainbranch.name + "/" + .folder.path
readme: file://README.md
- Refer to the setup section to learn more about the
port-app-config.ymlsetup process; - We leverage JQ JSON processor to map and transform GitHub objects to Port Entities;
- Click Here for the Bitbucket repository object structure.
- Click Here for the Bitbucket folder object structure.
Mapping supported resources
The above example shows a specific use case, but Port's Bitbucket app supports the ingestion of many other Bitbucket objects, to adapt the example 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.