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 }}
    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 }}
    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 }}
        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 }}
        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 }}
    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 }}
    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 }}
    operation: CREATE_RUN
    icon: GithubActions
    blueprint: myBlueprint
    action: myAction
    identifier: myEntity
    properties: |-
      {
        "text": "test",
        "number": 1,
        "boolean": true
      }

Examples

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