Skip to main content

Let developers enrich services using Gitops

This guide takes 10 minutes to complete, and aims to demonstrate Port's flexibility when working with Gitops.

  • This guide assumes you have a Port account and that you have finished the onboarding process. We will use the Service blueprint that was created during the onboarding process.
  • You will need a Git repository (Github, GitLab, or Bitbucket) in which you can place a workflow/pipeline that we will use in this guide. If you don't have one, we recommend creating a new repository named Port-actions.

The goal of this guide

In this guide we will enrich a service in Port using Gitops. In reality, this can be used by developers to independently add additional valuable data about their services to Port.

After completing it, you will get a sense of how it can benefit different personas in your organization:

  • Developers will be able to enrich their services without needing to nag devops engineers.
  • Platform engineers will be able to create RBAC-controlled actions for developers, empowering their independence.
  • R&D managers will be able to track additional, valuable data about services in the organization.

Add new properties to your Service blueprint

Let's start by adding two new properties to the Service blueprint, that we will later populate using Gitops.

  1. Go to your Builder, expand the Service blueprint, and click on New property.

  2. The first property will be the service's type, chosen from a predefined list of options. Fill out the form like this, then click Create:

  1. The second property will be the lifecycle state of the service, also chosen from a predefined list of options. Fill out the form like this, then click Create:

Note the colors of the inputs, this will make it easier to see a service's lifecycle in your catalog 😎

Model domains for your services

Services that share a business purpose (e.g. payments, shipping) are often grouped together using domains. Let's create a blueprint to represent a domain in Port:

  1. In your Builder, click on the Add button in the top right corner, then choose Custom blueprint:

  1. Click on the Edit JSON button in the top right corner, replace the content with the following definition, then click Create:
Blueprint JSON (click to expand)
"identifier": "domain",
"title": "Domain",
"icon": "TwoUsers",
"schema": {
"properties": {
"architecture": {
"title": "Architecture",
"type": "string",
"format": "url",
"spec": "embedded-url"
"required": []
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}

Connect your services to their domains

Now that we have a blueprint to represent a domain, let's connect it to our services. We will do this by adding a relation to the Service blueprint:

  1. Go to your Builder, expand the Service blueprint, and click on New relation:

  1. Fill out the form like this, then click Create:

Create domains via Gitops

Now that we have a Domain blueprint, we can create some domains in Port. This can be done manually from the UI, or via Gitops which is the method we will use in this guide.

  1. In your Port-actions (or equivalent) Github repository, create a new file named port.yml in the root directory, and use the following snippet as its content:
port.yml (click to expand)
- identifier: payment
title: Payment
blueprint: domain
- identifier: shipping
title: Shipping
blueprint: domain

  1. Head back to your software catalog, you will see that Port has created two new domain entities:

The architecture property is a URL to a Lucidchart diagram. This is a handy way to track a domain's architecture in your software catalog.

Create an action to enrich services

As platform engineers, we want to enable our developers to perform certain actions on their own. Let's create an action that developers can use to add data to a service, and allocate it to a domain.


As part of the onboarding process, you should already have an action named Send scorecard reminder in your self-service tab.

If you skipped the onboarding, follow the instructions listed here.

  1. Head to the Self-service page of your portal. Hover over the Scaffold a new service action, click the ... button in the top right corner, and choose "Edit":

  2. Click on the Backend tab.

Define backend type

Now we'll define the backend of the action. Port supports multiple invocation types, for this tutorial we will use a Github workflow, a GitLab pipeline, or a Jenkins pipeline(choose this option if you are using Bitbucket).

Note that you will need to have Port's Github app installed in your Github organization (the one that contains the repository you'll work with).

Fill out the form with your values:

  • Replace the Organization and Repository values with your values (this is where the workflow will reside and run).

  • Name the workflow port-enrich-service.yml.

  • Fill out your workflow details:

  • Scroll down to the Configure the invocation payload section.
    This is where you can define which data will be sent to your backend each time the action is executed.

    For this example, we will send some details that our backend needs to know - the user inputs, the entity, and the id of the action run.
    Copy the following JSON snippet and paste it in the payload code box:

    "port_context": {
    "entity": "{{ .entity.identifier }}",
    "runId": "{{ }}",
    "domain": "{{ .inputs.domain }}",
    "type": "{{ .inputs.type }}",
    "lifecycle": "{{ .inputs.lifecycle }}",

The last step is customizing the action's permissions. For simplicity's sake, we will use the default settings. For more information, see the permissions page. Click Create.

Setup the action's backend

Our action will create a pull-request in the service's repository, containing a port.yml file that will add data to the service in Port. Choose a backend type below to setup the workflow:

  1. First, let's create the necessary token and secrets. If you've already completed the scaffold a new service guide, you should already have these configured and you can skip this step.
  • Go to your Github tokens page, create a personal access token with repo and admin:org scope, and copy it (this token is needed to create a pull-request from our workflow).

  • Go to your Port application, click on the ... in the top right corner, then click Credentials. Copy your Client ID and Client secret.

  1. In your Port-actions (or equivalent) Github repository, create 3 new secrets under Settings->Secrets and variables->Actions:
  • ORG_ADMIN_TOKEN - the personal access token you created in the previous step.
  • PORT_CLIENT_ID - the client ID you copied from your Port app.
  • PORT_CLIENT_SECRET - the client secret you copied from your Port app.

We will now create a YML file that will serve as a template for our services' port.yml configuration file.

  • In your repository, create a file named enrichService.yml under /templates/ (its path should be /templates/enrichService.yml).
  • Copy the following snippet and paste it in the file's contents:
enrichService.yml (click to expand)
# enrichService.yml

- identifier: "{{ service_identifier }}"
blueprint: service
type: "{{ service_type }}"
lifecycle: "{{ service_lifecycle }}"
domain: "{{ domain_identifier }}"

Now let's create the file that contains our logic:

In the same repository, under .github/workflows, create a new file named port-enrich-service.yml and use the following snippet as its content:

Github workflow (click to expand)
name: Enrich service
required: true
description: Includes the entity identifier and the action's run id
required: true
description: The domain to assign the service to
type: string
required: true
description: The type of the service
type: string
required: true
description: The lifecycle state of the service
type: string
runs-on: ubuntu-latest
# Checkout the workflow's repository
- uses: actions/checkout@v3
# Checkout the service's repository
- uses: actions/checkout@v3
repository: "${{ github.repository_owner }}/${{ fromJson(inputs.port_context).entity }}"
path: ./targetRepo
token: ${{ secrets.ORG_ADMIN_TOKEN }}
- name: Copy template yml file
run: |
cp templates/enrichService.yml ./targetRepo/port.yml
- name: Update new file data
run: |
sed -i 's/{{ service_identifier }}/${{ fromJson(inputs.port_context).entity }}/' ./targetRepo/port.yml
sed -i 's/{{ domain_identifier }}/${{ inputs.domain }}/' ./targetRepo/port.yml
sed -i 's/{{ service_type }}/${{ inputs.type }}/' ./targetRepo/port.yml
sed -i 's/{{ service_lifecycle }}/${{ inputs.lifecycle }}/' ./targetRepo/port.yml
- name: Open a pull request
uses: peter-evans/create-pull-request@v5
token: ${{ secrets.ORG_ADMIN_TOKEN }}
path: ./targetRepo
commit-message: Enrich service - ${{ fromJson(inputs.port_context).entity}}
committer: GitHub <>
author: ${{ }} <${{ }}>
signoff: false
branch: add-port-yml
delete-branch: true
title: Create port.yml - ${{ fromJson(inputs.port_context).entity }}
body: |
Add port.yaml to enrich service in Port.
draft: false
- name: Create a log message
uses: port-labs/port-github-action@v1
clientId: ${{ secrets.PORT_CLIENT_ID }}
clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
operation: PATCH_RUN
runId: ${{ fromJson(inputs.port_context).runId }}
logMessage: Pull request to add port.yml created successfully for service "${{ fromJson(inputs.port_context).entity }}" 🚀

The action is ready to be executed 🚀

Execute the action

  1. After creating an action, it will appear under the Self-service page. Find your new Enrich service action, and click on Execute.

  2. Choose a service from the dropdown, a domain to assign it to, and any values for its type and lifecycle, then click Execute:

  1. A small popup will appear, click on View details:

This page provides details about the action run. We can see that the backend returned Success and the pull-request was created successfully.

  1. Head over to your service's repository, you will see that a new pull-request was created:

  1. Merge the pull-request, then head back to your software catalog.

  2. Find your service, and click on its identifier. This will take you to the service's catalog page, where you can see your new properties populated with data:

All done! 💪🏽

Possible daily routine integrations

  • Fetch data from a Sentry project and reflect it in your software catalog.
  • Create and onboard services with a few clicks from your developer portal.


Gitops is a common practice in modern software development, as it ensures that the state of your infrastructure is always in sync with your codebase.
Port allows you to easily integrate your Gitops practices with your software catalog, reflecting the state of your infrastructure, and allowing you to empower your developers with controlled actions.

More guides & tutorials will be available soon, in the meantime feel free to reach out with any questions via our community slack or Github project.