GitHub Workflow

Our GitHub action allows you to create/update and query entities in Port directly from your GitHub workflows.

public repository

Our GitHub action is open source - see it here

💡 Common Github workflow usage

Port's GitHub action provides a native way to integrate Port with your GitHub workflows, for example:

• Report the status of a running CI job;
• Update the software catalog about a new build version for a microservice;
• Get existing entities.

Installation

To install Port's GitHub action, follow these steps:

1. Add the following line as a step in your GitHub workflow:

- uses: port-labs/port-github-action@v1

2. Add your Port CLIENT_ID and CLIENT_SECRET as GitHub secrets;
   1. This step is not mandatory, but it is recommended in order to not pass the CLIENT_ID and CLIENT_SECRET in plaintext in your workflows;
3. Make sure you have an existing blueprint in your Port installation to create/update entities using the GitHub action.

Usage

Port's GitHub action supports the following methods:

• Create/Update catalog entities - invoked with the UPSERT operation, receives the identifier and other properties of a new entity or an entity that needs to be updated;
• Bulk Create/Update catalog entities - invoked with the BULK_UPSERT operation, receives the entities definitions of some new entities or entities that needs to be updated;
• Get catalog entities - invoked with the GET operation, receives the identifier of an existing entity and retrieves it for use in your CI;
• Search catalog entities - invoked with the SEARCH operation, receives a query and retrieves the entities for use in your CI;
• Delete catalog entities - invoked with the DELETE operation, receives the identifier of an existing entity and deletes it;
• Update a running action - invoked with the PATCH_RUN operation, receives the identifier of an existing action run along with other properties of the run that need to be updated.
• Create an action run - invoked with the CREATE_RUN operation, receives the identifier of an existing blueprint, action and entity (optional), along with input properties to run the action with.

Create/Update Entity

- uses: port-labs/port-github-action@v1
  with:
    clientId: ${{ secrets.CLIENT_ID }}
    clientSecret: ${{ secrets.CLIENT_SECRET }}
    baseUrl: https://api.getport.io
    operation: UPSERT
    identifier: myEntity
    icon: myIcon
    blueprint: myBlueprint
    team: "['myTeam']"
    properties: |-
      {
        "myStringProp": "My value",
        "myNumberProp": 1,
        "myBooleanProp": true,
        "myArrayProp": ["myVal1", "myVal2"],
        "myObjectProp": {"myKey": "myVal", "myExtraKey": "myExtraVal"}
      }

Bulk Create/Update Entities

- uses: port-labs/port-github-action@v1
  with:
    clientId: ${{ secrets.CLIENT_ID }}
    clientSecret: ${{ secrets.CLIENT_SECRET }}
    baseUrl: https://api.getport.io
    operation: BULK_UPSERT
    runId: myRunId
    entities: |-
      [
       {
          "identifier": "myEntity",
          "icon": "myIcon",
          "blueprint": "myBlueprint",
          "team": [
             "myTeam"
          ],
          "properties": {
             "myStringProp": "My value",
             "myNumberProp": 1,
             "myBooleanProp": true,
             "myArrayProp": [
                "myVal1",
                "myVal2"
             ],
             "myObjectProp": {
                "myKey": "myVal",
                "myExtraKey": "myExtraVal"
             }
          }
       }
      ]

Get Entity

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: myEntity
        blueprint: myBlueprint
use-entity:
  runs-on: ubuntu-latest
  needs: get-entity
  steps:
    - run: echo '${{needs.get-entity.outputs.entity}}' | jq .properties.myProp

Search Entities

search-entities:
  runs-on: ubuntu-latest
  outputs:
    entities: ${{ steps.port-github-action.outputs.entities }}
  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: SEARCH
        query: |-
          {
             "rules": [
                {
                   "operator": "=",
                   "value": "myEntity",
                   "property": "$identifier"
                }
             ],
             "combinator": "and"
          }
use-entities:
  runs-on: ubuntu-latest
  needs: search-entities
  steps:
    - run: echo '${{needs.search-entities.outputs.entities}}' | jq .[0].myProp

Delete Entity

- uses: port-labs/port-github-action@v1
  with:
    clientId: ${{ secrets.CLIENT_ID }}
    clientSecret: ${{ secrets.CLIENT_SECRET }}
    baseUrl: https://api.getport.io
    operation: DELETE
    identifier: myEntity
    blueprint: myBlueprint

Update Running 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: myRunId
    status: "SUCCESS"
    logMessage: "My log message"
    summary: "My summary"
    link: '["https://mylink.com"]'

Create Action Run

- uses: port-labs/port-github-action@v1
  with:
    clientId: ${{ secrets.CLIENT_ID }}
    clientSecret: ${{ secrets.CLIENT_SECRET }}
    baseUrl: https://api.getport.io
    operation: CREATE_RUN
    icon: GithubActions
    blueprint: myBlueprint
    action: myAction
    identifier: myEntity
    properties: |-
      {
        "text": "test",
        "number": 1,
        "boolean": true
      }

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, available at https://app.getport.io, your Port API URL is https://api.getport.io
• If you use the US region of Port, available at https://app.us.getport.io, your Port API URL is https://api.us.getport.io

Examples

Refer to the examples page for practical examples of Port's GitHub action.