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 }}
    baseUrl: https://api.getport.io
    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 }}"
      }

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

If you use the EU region of Port (https://app.getport.io), your API URL is https://api.getport.io.
If you use the US region of Port (https://app.us.getport.io), your API URL is https://api.us.getport.io.

tip

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 }}
        baseUrl: https://api.getport.io
        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

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

If you use the EU region of Port (https://app.getport.io), your API URL is https://api.getport.io.
If you use the US region of Port (https://app.us.getport.io), your API URL is https://api.us.getport.io.

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 }}
    baseUrl: https://api.getport.io
    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",
      }

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

If you use the EU region of Port (https://app.getport.io), your API URL is https://api.getport.io.
If you use the US region of Port (https://app.us.getport.io), your API URL is https://api.us.getport.io.

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 }}
    baseUrl: https://api.getport.io
    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": "deploy_image",
  "title": "Deploy image",
  "icon": "DefaultProperty",
  "description": "Deploy image version",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {},
      "required": [],
      "order": []
    },
    "blueprintIdentifier": "image"
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://example.com",
    "agent": false,
    "synchronized": false,
    "method": "POST",
    "headers": {
      "RUN_ID": "{{ .run.id }}"
    },
    "body": {
      "action": "{{ .action }}",
      "trigger": "{{ .trigger | {by, origin, at} }}",
      "port_context": {
        "entity": "{{.entity.identifier}}",
        "blueprint": "{{.action.blueprint}}",
        "runId": "{{.run.id}}",
        "operation": "{{.trigger.operation}}"
      }
    }
  },
  "requiredApproval": false
}

info

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 }}
    baseUrl: https://api.getport.io
    operation: PATCH_RUN
    runId: ${{ env.PORT_RUN_ID }}
    icon: GithubActions
    status: "SUCCESS"
    logMessage: "Deployment completed successfully"

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

If you use the EU region of Port (https://app.getport.io), your API URL is https://api.getport.io.
If you use the US region of Port (https://app.us.getport.io), your API URL is https://api.us.getport.io.

tip

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.

Basic create/update example​

Basic get example​

Relation example​

Basic update run example​

Basic create/update example

Basic get example

Relation example

Basic update run example