Examples
Basic create/update example​
In this example you will create blueprints for ciJob and image entities, and a relation between them. Using Port's GitHub action you will create new entities every time the GitHub workflow runs:
Image blueprint
{
"identifier": "image",
"title": "Image",
"icon": "Docker",
"schema": {
"properties": {
"synkHighVulnerabilities": {
"type": "string",
"icon": "Snyk",
"title": "Synk High Vaulnerabilities"
},
"synkMediumVulnerabilities": {
"type": "string",
"icon": "Snyk",
"title": "Synk Medium Vaulnerabilities"
},
"imageTag": {
"type": "string",
"title": "Image Tag"
},
"gitRepoUrl": {
"type": "string",
"format": "url",
"title": "Git Url",
"description": "Git Url for the sourcecode"
},
"imageRegistry": {
"type": "string",
"format": "url",
"title": "Image Registry",
"description": "Docker registry"
},
"unitTestCoverage": {
"type": "number",
"title": "Unit Test coverage (%)",
"description": "The unit test coverage pecentage"
},
"integTestCoverage": {
"type": "number",
"title": "Integ Test coverage (%)",
"description": "The integration test coverage pecentage"
},
"size": {
"type": "number",
"title": "Image Size (GB)",
"description": "The image size in Gigabyte"
}
},
"required": []
},
"calculationProperties": {}
}
CI Job blueprint (including the image relation)
{
"identifier": "ciJob",
"title": "CI Job",
"icon": "CICD",
"schema": {
"properties": {
"triggeredBy": {
"type": "string",
"icon": "TwoUsers",
"title": "Triggered By",
"description": "The user who triggered the run"
},
"commitHash": {
"type": "string",
"title": "Commit Hash"
},
"jobBranch": {
"type": "string",
"icon": "Git",
"format": "url",
"title": "Job branch"
},
"runLink": {
"type": "string",
"format": "url",
"title": "Action Run Link"
}
},
"required": []
},
"relations": {
"image": {
"title": "Job Images",
"target": "image",
"required": false,
"many": true
}
},
"calculationProperties": {}
}
After creating the blueprints, you can add the following snippet to your GitHub workflow yml file to create the ciJob entity in your GitHub workflow:
- uses: port-labs/port-github-action@v1
with:
clientId: ${{ secrets.CLIENT_ID }}
clientSecret: ${{ secrets.CLIENT_SECRET }}
operation: UPSERT
identifier: new-cijob-run
icon: GithubActions
blueprint: ciJob
properties: |
{
"commitHash": "${{ env.GITHUB_SHA }}",
"jobBranch": "${{ env.GITHUB_SERVER_URL }}/${{ env.GITHUB_REPOSITORY }}/tree/${{ env.GITHUB_REF_NAME }}",
"runLink": "${{ env.GITHUB_SERVER_URL }}/${{ env.GITHUB_REPOSITORY }}/actions/runs/${{ env.GITHUB_RUN_ID }}",
"triggeredBy": "${{ env.GITHUB_ACTOR }}"
}
For security reasons it is recommended to save the CLIENT_ID and CLIENT_SECRET as GitHub Secrets, and access them as shown in the example above.
Basic get example​
The following example gets the ciJob entity from the previous example. This can be useful if your CI process needs to reference data from the ciJob (for example, the user who triggered the last job) when deploying the latest version of your service.
Add the following jobs to your GitHub workflow yml file:
get-entity:
runs-on: ubuntu-latest
outputs:
entity: ${{ steps.port-github-action.outputs.entity }}
steps:
- id: port-github-action
uses: port-labs/port-github-action@v1
with:
clientId: ${{ secrets.CLIENT_ID }}
clientSecret: ${{ secrets.CLIENT_SECRET }}
operation: GET
identifier: new-cijob-run
blueprint: ciJob
use-entity:
runs-on: ubuntu-latest
needs: get-entity
steps:
- run: echo '${{needs.get-entity.outputs.entity}}' | jq .properties.triggeredBy
The first job get-entity, uses the GitHub action to get the new-cijob-run entity.
The second job use-entity, uses the output from the first job, and prints the triggeredBy property of the entity.
Relation example​
The following example adds an image entity, in addition to the ciJob entity shown in the previous example. The image entity represents an artifact generated by the ciJob run.
Add the following snippet to your GitHub workflow yml file:
- uses: port-labs/port-github-action@v1
with:
clientId: ${{ secrets.CLIENT_ID }}
clientSecret: ${{ secrets.CLIENT_SECRET }}
operation: UPSERT
identifier: example-image
title: Example Image
icon: Docker
blueprint: image
properties: |
{
"imageTag": "v1",
"synkHighVulnerabilities": "0",
"synkMediumVulnerabilities": "0",
"gitRepoUrl": "https://github.com/my-org/my-cool-repo",
"imageRegistry": "docker.io/cool-image",
"size": "0.71",
"unitTestCoverage": "20",
"unitTestCoverage": "50",
}
All that’s left is to map the new image entity to the ciJob , thus making it possible to know which image was created by the ciJob.
- uses: port-labs/port-github-action@v1
with:
clientId: ${{ secrets.CLIENT_ID }}
clientSecret: ${{ secrets.CLIENT_SECRET }}
operation: UPSERT
identifier: new-cijob-run
icon: GithubActions
blueprint: ciJob
relations: |
{
"image": ["example-image"]
}
That's it! The entities are updated and visible in the UI.
Basic update run example​
In this example you will create a self-service action that deploys the latest version of your service, and updates the action run with the deployment status.
Add the following action to your image blueprint actions:
Deploy image action
[
{
"identifier": "image_deploy_image",
"title": "Deploy image",
"description": "Deploy image version",
"trigger": {
"type": "self-service",
"operation": "DAY-2",
"userInputs": {
"properties": {}
},
"blueprintIdentifier": "image"
},
"invocationMethod": {
"type": "WEBHOOK",
"url": "https://example.com",
"body": {
"action": "{{ .action.identifier[(\"image_\" | length):] }}",
"resourceType": "run",
"status": "TRIGGERED",
"trigger": "{{ .trigger | {by, origin, at} }}",
"context": {
"entity": "{{.entity.identifier}}",
"blueprint": "{{.action.blueprint}}",
"runId": "{{.run.id}}"
},
"payload": {
"entity": "{{ (if .entity == {} then null else .entity end) }}",
"action": {
"invocationMethod": {
"type": "WEBHOOK",
"url": "https://example.com"
},
"trigger": "{{.trigger.operation}}"
},
"properties": {},
"censoredProperties": "{{.action.encryptedProperties}}"
}
}
},
"publish": true
}
]
The example here is meant to show a common flow when using a Port self-service action and then using Port's GitHub action to update its logs, status and other information.
In order to use Port's GitHub action to make these updates, you will need your backend to either be a GitHub workflow or for a different backend of your choosing to trigger a GitHub workflow as part of its logic
After triggering the action in Port, a new action run will be created in Port (and a matching runId will be generated). The runId can be used to update the action status and reports logs to Port.
To update the new self-service action run, add the following snippet to your GitHub workflow yml file (note you will need to pass the correct runId to the action):
- uses: port-labs/port-github-action@v1
with:
clientId: ${{ secrets.CLIENT_ID }}
clientSecret: ${{ secrets.CLIENT_SECRET }}
operation: PATCH_RUN
runId: ${{ env.PORT_RUN_ID }}
icon: GithubActions
status: "SUCCESS"
logMessage: "Deployment completed successfully"
The example above shows how to update the status and add a new log message to the action run, but it is also possible to update just a specific field of an action run.
For example it is possible to trigger the GitHub action and just update the log, without changing its status.
Note that once a Port action run has a status, it can no longer be updated and changes made to the catalog can no longer be tied to that action, so it is considered a best practice to update the status of an action only when it has finished performing all of its catalog changes and logic
That's it! The action status and logs are updated in Port.