Examples
Mapping repositories, file contents and pull requestsโ
In the following example you will ingest your GitHub repositories, their README.md file contents and pull requests to Port, you may use the following Port blueprint definitions and port-app-config.yml
:
Microservice blueprint
{
"identifier": "microservice",
"title": "Microservice",
"icon": "Microservice",
"schema": {
"properties": {
"readme": {
"title": "README",
"type": "string",
"format": "markdown"
},
"repositoryUrl": {
"title": "Repository URL",
"type": "string",
"format": "url"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}
}
Pull request blueprint
{
"identifier": "pullRequest",
"title": "Pull Request",
"schema": {
"properties": {
"creator": {
"title": "Creator",
"type": "string"
},
"assignees": {
"title": "Assignees",
"type": "array"
},
"reviewers": {
"title": "Reviewers",
"type": "array"
},
"status": {
"title": "Status",
"type": "string",
"enum": ["merged", "open", "closed"],
"enumColors": {
"merged": "purple",
"open": "green",
"closed": "red"
}
},
"closedAt": {
"title": "Closed At",
"type": "string",
"format": "date-time"
},
"updatedAt": {
"title": "Updated At",
"type": "string",
"format": "date-time"
},
"mergedAt": {
"title": "Merged At",
"type": "string",
"format": "date-time"
},
"description": {
"title": "Description",
"type": "string",
"format": "markdown"
},
"link": {
"format": "url",
"type": "string"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}
}
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 repository name.
title: ".name"
blueprint: '"microservice"'
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
repositoryUrl: .html_url
- kind: pull-request
selector:
query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
port:
entity:
mappings:
identifier: ".head.repo.name + (.id|tostring)" # The Entity identifier will be the repository name + the pull request ID.
title: ".title"
blueprint: '"pullRequest"'
properties:
creator: ".user.login"
assignees: "[.assignees[].login]"
reviewers: "[.requested_reviewers[].login]"
status: ".status" # merged, closed, opened
closedAt: ".closed_at"
updatedAt: ".updated_at"
mergedAt: ".merged_at"
description: ".body"
prNumber: ".id"
link: ".html_url"
- Refer to the setup section to learn more about the
port-app-config.yml
setup process; - We leverage JQ JSON processor to map and transform GitHub objects to Port Entities;
- Click Here for the GitHub repository object structure.
- Click Here for the GitHub pull request object structure.
After creating the blueprints and committing the port-app-config.yml
file to your .github-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, workflows and workflow runsโ
In the following example you will ingest your GitHub repositories, their workflows and workflow runs to Port, you may use the following Port blueprint definitions and port-app-config.yml
:
Microservice blueprint
{
"identifier": "microservice",
"title": "Microservice",
"icon": "Microservice",
"schema": {
"properties": {
"readme": {
"title": "README",
"type": "string",
"format": "markdown"
},
"repositoryUrl": {
"title": "Repository URL",
"type": "string",
"format": "url"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}
}
Workflow blueprint
{
"identifier": "workflow",
"title": "Workflow",
"icon": "Github",
"schema": {
"properties": {
"path": {
"title": "Path",
"type": "string"
},
"status": {
"title": "Status",
"type": "string",
"enum": [
"active",
"deleted",
"disabled_fork",
"disabled_inactivity",
"disabled_manually"
],
"enumColors": {
"active": "green",
"deleted": "red"
}
},
"createdAt": {
"title": "Created At",
"type": "string",
"format": "date-time"
},
"updatedAt": {
"title": "Updated At",
"type": "string",
"format": "date-time"
},
"deletedAt": {
"title": "Deleted At",
"type": "string",
"format": "date-time"
},
"link": {
"title": "Link",
"type": "string",
"format": "url"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {
"service": {
"target": "microservice",
"required": true,
"many": false
}
}
}
Workflow run blueprint
{
"identifier": "workflowRun",
"title": "Workflow Run",
"icon": "Github",
"schema": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"triggeringActor": {
"title": "Triggering Actor",
"type": "string"
},
"status": {
"title": "Status",
"type": "string",
"enum": [
"completed",
"action_required",
"cancelled",
"startup_failure",
"failure",
"neutral",
"skipped",
"stale",
"success",
"timed_out",
"in_progress",
"queued",
"requested",
"waiting"
],
"enumColors": {
"queued": "yellow",
"in_progress": "yellow",
"success": "green",
"failure": "red"
}
},
"conclusion": {
"title": "Conclusion",
"type": "string",
"enum": [
"completed",
"action_required",
"cancelled",
"startup_failure",
"failure",
"neutral",
"skipped",
"stale",
"success",
"timed_out",
"in_progress",
"queued",
"requested",
"waiting"
],
"enumColors": {
"queued": "yellow",
"in_progress": "yellow",
"success": "green",
"failure": "red"
}
},
"createdAt": {
"title": "Created At",
"type": "string",
"format": "date-time"
},
"runStartedAt": {
"title": "Run Started At",
"type": "string",
"format": "date-time"
},
"updatedAt": {
"title": "Updated At",
"type": "string",
"format": "date-time"
},
"runNumber": {
"title": "Run Number",
"type": "number"
},
"runAttempt": {
"title": "Run Attempts",
"type": "number"
},
"link": {
"title": "Link",
"type": "string",
"format": "url"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {
"workflow": {
"target": "workflow",
"required": true,
"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 repository name.
title: ".name"
blueprint: '"microservice"'
properties:
readme: file://README.md
repositoryUrl: .html_url
- kind: workflow
selector:
query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
port:
entity:
mappings:
identifier: ".repo + (.id|tostring)"
title: ".name"
blueprint: '"workflow"'
properties:
path: ".path"
status: ".state"
createdAt: ".created_at"
updatedAt: ".updated_at"
link: ".html_url"
relations:
service: ".repo"
- kind: workflow-run
selector:
query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
port:
entity:
mappings:
identifier: ".repository.name + (.id|tostring)"
title: ".display_title"
blueprint: '"workflowRun"'
properties:
name: ".name"
triggeringActor: ".triggering_actor.login"
status: ".status"
conclusion: ".conclusion"
createdAt: ".created_at"
runStartedAt: ".run_started_at"
updatedAt: ".updated_at"
deletedAt: ".deleted_at"
runNumber: ".run_number"
runAttempt: ".run_attempt"
link: ".html_url"
relations:
workflow: ".repository.name + (.workflow_id|tostring)"
- Refer to the setup section to learn more about the
port-app-config.yml
setup process; - We leverage JQ JSON processor to map and transform GitHub objects to Port Entities;
- Click Here for the GitHub repository object structure.
- Click Here for the GitHub workflow object structure.
- Click Here for the GitHub workflow run object structure.
After creating the blueprints and committing the port-app-config.yml
file to your .github-private
or to a specific repository, you will see new entities in Port matching your repositories alongside their workflows and workflow runs. (Remember that the port-app-config.yml
file has to be in the default branch of the repository to take effect).
Mapping repositories and issuesโ
In the following example you will ingest your GitHub repositories and their issues to Port, you may use the following Port blueprint definitions and port-app-config.yml
:
Microservice blueprint
{
"identifier": "microservice",
"title": "Microservice",
"icon": "Microservice",
"schema": {
"properties": {
"readme": {
"title": "README",
"type": "string",
"format": "markdown"
},
"repositoryUrl": {
"title": "Repository URL",
"type": "string",
"format": "url"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}
}
Issue blueprint
{
"identifier": "issue",
"title": "Issue",
"icon": "Github",
"schema": {
"properties": {
"creator": {
"title": "Creator",
"type": "string"
},
"assignees": {
"title": "Assignees",
"type": "array"
},
"labels": {
"title": "Labels",
"type": "array"
},
"status": {
"title": "Status",
"type": "string",
"enum": ["open", "closed"],
"enumColors": {
"open": "green",
"closed": "purple"
}
},
"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"
},
"description": {
"title": "Description",
"type": "string",
"format": "markdown"
},
"issueNumber": {
"title": "Issue Number",
"type": "number"
},
"link": {
"title": "Link",
"type": "string",
"format": "url"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {
"service": {
"target": "microservice",
"required": true,
"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 repository name.
title: ".name"
blueprint: '"microservice"'
properties:
readme: file://README.md
repositoryUrl: .html_url
- kind: issue
selector:
query: ".pull_request == null" # JQ boolean query. If evaluated to false - skip syncing the object.
port:
entity:
mappings:
identifier: ".repo + (.id|tostring)"
title: ".title"
blueprint: '"issue"'
properties:
creator: ".user.login"
assignees: "[.assignees[].login]"
labels: "[.labels[].name]"
status: ".state"
createdAt: ".created_at"
closedAt: ".closed_at"
updatedAt: ".updated_at"
description: ".body"
issueNumber: ".number"
link: ".html_url"
relations:
service: ".repo"
- Refer to the setup section to learn more about the
port-app-config.yml
setup process; - We leverage JQ JSON processor to map and transform GitHub objects to Port Entities;
- Click Here for the GitHub repository object structure.
- Click Here for the GitHub issue object structure.
After creating the blueprints and committing the port-app-config.yml
file to your .github-private
or to a specific repository, you will see new entities in Port matching your repositories alongside their issues. (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 GitHub 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
:
Microservice blueprint
{
"identifier": "microservice",
"title": "Microservice",
"icon": "Microservice",
"schema": {
"properties": {
"readme": {
"title": "README",
"type": "string",
"format": "markdown"
},
"repositoryUrl": {
"title": "Repository URL",
"type": "string",
"format": "url"
}
},
"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"
title: ".folder.name"
blueprint: '"microservice"'
properties:
repositoryUrl: .repo.html_url + "/tree/" + .repo.default_branch + "/" + .folder.path
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
- Refer to the setup section to learn more about the
port-app-config.yml
setup process; - We leverage JQ JSON processor to map and transform GitHub objects to Port Entities;
- Click Here for the GitHub repository object structure.
- Click Here for the GitHub folder object structure.
Mapping supported resourcesโ
The above example shows a specific use case, but Port's GitHub app supports the ingestion of many other GitHub objects, to adapt the example above, use the GitHub 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.