Skip to main content

GitOps

Port's GitLab integration makes it possible to manage Port entities with a GitOps approach, making your code projects into the source of truth for the various infrastructure assets you want to manage.

Apphost prerequisite

When installing the Gitlab integration, the appHost parameter must be provided in order to use GitOps.
Without it, the integration will not be able to receive webhook events about pushes to the port.yml file.

Common use cases​

  • Use GitLab as the source-of-truth for your microservices, projects, packages, libraries and other software catalog assets;
  • Allow developers to keep the catalog up-to-date, by making updates to files in their Git projects;
  • Create a standardized way to document software catalog assets in your organization;

Managing entities using GitOps​

To manage entities using GitOps, you will need to add a port.yml file to the default branch (usually main) of your project.

The port.yml file can specify one or more Port entities that will be ingested to Port, and any change made to the port.yml file will also be reflected inside Port.

This configuration turns your GitLab projects to the source-of-truth for the software catalog.

GitOps port.yml file​

The port.yml file is how you specify your Port entities that are managed using GitOps and whose data is ingested from your Git projects.

Here are examples for valid port.yml files:

identifier: myEntity
title: My Entity
blueprint: myBlueprint
properties:
  myStringProp: myValue
  myNumberProp: 5
  myUrlProp: https://example.com
relations:
  mySingleRelation: myTargetEntity
  myManyRelation:
    - myTargetEntity1
    - myTargetEntity2

Since both of the valid port.yml formats follow the same structure, the following section will explain the format based on the single entity example.

port.yml structure​

Here is an example port.yml file:

identifier: myEntity
title: My Entity
blueprint: myBlueprint
properties:
  myStringProp: myValue
  myNumberProp: 5
  myUrlProp: https://example.com
relations:
  mySingleRelation: myTargetEntity
  myManyRelation:
    - myTargetEntity1
    - myTargetEntity2
  • The identifier key is used to specify the identifier of the entity that the app will create and keep up-to-date when changes occur:
identifier: myEntity
title: My Entity
  ...
  • The title key is used to specify the title of the entity:
identifier: myEntity
title: My Entity
  ...
  • The blueprint key is used to specify the identifier of the blueprint to create this entity from:
...
title: My Entity
blueprint: myBlueprint
  ...
  • The properties key is used to map the values to the different properties of the entity:
...
title: My Entity
blueprint: myBlueprint
properties:
  myStringProp: myValue
  myNumberProp: 5
  myUrlProp: https://example.com
  ...
  • The relations key is used to map target entities to the different relations of the entity:
...
properties:
  myStringProp: myValue
  myNumberProp: 5
  myUrlProp: https://example.com
relations:
  mySingleRelation: myTargetEntity

Setting null properties​

When you want to clear a property's value in Port, you can explicitly set it to null in your port.yml file. Let's see how to do this:

identifier: myEntity
title: My Entity
blueprint: myBlueprint
properties:
  description: null  
  owner: null
Difference between null and omitting

When you omit a property entirely from the port.yml, Port will keep its existing value. Setting a property to null explicitly tells Port to clear that property's value.

Ingesting project file contents​

It is possible to use the contents of files in the repository as the value for entity properties using a simple reference.

The following example will read the string contents of ~/module1/README.md and upload it to myStringProp of the specified entity.

Repository folder structure used for the example:

root
|
+- port.yml
|
+-+ module1
|   |
|   +- README.md
|   |
|   +-+ src
...

port.yml file:

blueprint: code_module
title: Module 1
identifier: module_1_entity
properties:
  myStringProp: file://module1/README.md

Using relative paths​

It is also possible to use paths relative to the location of the port.yml spec file.

For example: file://./ is used to reference a file in the same directory as the port.yml file. file://../ is used to reference a file that is one directory above and so on.

The following example reads README.md and module1/requirements.txt using paths relative to port.yml

Repository folder structure used for the example:

root
|
+-+ meta
|   |
|   +-- port.yml
|   |
|   +-+ README.md
|
+-+ module1
|   |
|   +- requirements.txt
|   |
|   +-+ src
...

port.yml file:

blueprint: code_module
title: Module 1
identifier: module_1_entity
properties:
  readme: file://./README.md
  module1Requirements: file://../module1/requirements.txt

Advanced​

Refer to the advanced page for advanced use cases and configurations.