Skip to content

Update sync-service-entities-to-incident-io.md #2759

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Update sync-service-entities-to-incident-io.md #2759

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a7b3652
Update sync-service-entities-to-incident-io.md to enhance clarity and…
kodjomiles Sep 2, 2025
04a5295
Merge branch 'main' into PORT-11540-bug-incident-io-integration-guide…
kodjomiles Sep 3, 2025
169915f
Merge branch 'main' into PORT-11540-bug-incident-io-integration-guide…
kodjomiles Sep 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
272 changes: 159 additions & 113 deletions docs/guides/all/sync-service-entities-to-incident-io.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
sidebar_position: 8
displayed_sidebar: null
description: Learn how to sync your Port service entities into incident.io catalog.
description: Learn how to sync your Port service entities into incident.io catalog for better visibility.
---

import Tabs from "@theme/Tabs"
Expand All @@ -12,109 +12,132 @@ import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_expl
# Sync Port Services to incident.io
This guide demonstrates how to set up a GitHub workflow that periodically syncs service entities from Port into incident.io's catalog, ensuring better visibility and context for your services during incident management.


## Prerequisites

- You need a Port account and should have completed the [onboarding process](/getting-started/overview)
- A GitHub repository where you can trigger a workflow for this guide
- An [incident.io](https://app.incident.io/) account and an API key

## Set up required secrets and permissions

- In your GitHub repository, [go to **Settings > Secrets**](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) and add the following secrets:
- `PORT_CLIENT_ID` - Port Client ID [learn more](/build-your-software-catalog/custom-integration/api/#get-api-token)
- `PORT_CLIENT_SECRET` - Port Client Secret [learn more](/build-your-software-catalog/custom-integration/api/#get-api-token)
- `INCIDENT_IO_API_KEY` - [API key](https://app.incident.io/settings/api-keys) from your incident.io dashboard with the following permissions:
- `Can manage catalog types and edit catalog data`
- `Can view catalog types and entries`
- `INCIDENT_IO_CATALOG_TYPE_ID` - Incident.io catalog type ID. To be created in [this section](#create-a-catalog-item-in-incident-io)
- Complete the [onboarding process](/getting-started/overview).
- A GitHub repository where you can trigger a workflow for this guide.
- An [incident.io](https://app.incident.io/) account with **admin access** to create API keys.
- [Port's GitHub app](https://github.com/apps/getport-io) needs to be installed (required for GitHub Actions implementation)

:::info Admin Access Required
You need admin access to your incident.io organization to create API keys. If you don't have admin access, contact your incident.io administrator to create the API key for you.
:::

Below is the JSON for the `Service` blueprint that represents the service entities you will sync from Port to incident.io:
## Set up required secrets and permissions

<details>
<summary><b>Service blueprint (click to expand)</b></summary>

```json showLineNumbers
{
"identifier": "service",
"title": "Service",
"icon": "Github",
"schema": {
"properties": {
"readme": {
"title": "README",
"type": "string",
"format": "markdown",
"icon": "Book"
},
"url": {
"title": "URL",
"format": "url",
"type": "string",
"icon": "Link"
},
"language": {
"icon": "Git",
"type": "string",
"title": "Language",
"enum": [
"GO",
"Python",
"Node",
"React"
],
"enumColors": {
"GO": "red",
"Python": "green",
"Node": "blue",
"React": "yellow"
}
},
"type": {
"title": "Type",
"description": "This service's type",
"type": "string",
"enum": [
"Backend",
"Frontend",
"Library"
],
"enumColors": {
"Backend": "purple",
"Frontend": "pink",
"Library": "green"
In your GitHub repository, [go to **Settings > Secrets**](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) and add the following secrets:
- `PORT_CLIENT_ID` - Port Client ID [learn more](/build-your-software-catalog/custom-integration/api/#get-api-token).
- `PORT_CLIENT_SECRET` - Port Client Secret [learn more](/build-your-software-catalog/custom-integration/api/#get-api-token).
- `INCIDENT_IO_API_KEY` - [API key](https://app.incident.io/settings/api-keys) from your incident.io dashboard with the following permissions:
- `Can manage catalog types and edit catalog data`
- `Can view catalog types and entries`
- `INCIDENT_IO_CATALOG_TYPE_ID` - Incident.io catalog type ID. To be created in [this section](#create-a-catalog-type-in-incident-io).

## Set up data model

You'll need a `Service` blueprint in Port to represent the service entities you want to sync to incident.io. If you don't already have one, Follow the steps below:

1. Go to the [Builder](https://app.getport.io/settings/data-model) page of your portal.

2. Click on `+ Blueprint`.

3. Click on the `{...}` button in the top right corner, and choose `Edit JSON`.

4. Add the following JSON schema:

<details>
<summary><b>Service blueprint (click to expand)</b></summary>

```json showLineNumbers
{
"identifier": "service",
"title": "Service",
"icon": "Github",
"schema": {
"properties": {
"readme": {
"title": "README",
"type": "string",
"format": "markdown",
"icon": "Book"
},
"url": {
"title": "URL",
"format": "url",
"type": "string",
"icon": "Link"
},
"language": {
"icon": "Git",
"type": "string",
"title": "Language",
"enum": [
"GO",
"Python",
"Node",
"React"
],
"enumColors": {
"GO": "red",
"Python": "green",
"Node": "blue",
"React": "yellow"
}
},
"type": {
"title": "Type",
"description": "This service's type",
"type": "string",
"enum": [
"Backend",
"Frontend",
"Library"
],
"enumColors": {
"Backend": "purple",
"Frontend": "pink",
"Library": "green"
},
"icon": "DefaultProperty"
},
"lifecycle": {
"title": "Lifecycle",
"type": "string",
"enum": [
"Production",
"Experimental",
"Deprecated"
],
"enumColors": {
"Production": "green",
"Experimental": "yellow",
"Deprecated": "red"
},
"icon": "DefaultProperty"
}
},
"icon": "DefaultProperty"
"required": []
},
"lifecycle": {
"title": "Lifecycle",
"type": "string",
"enum": [
"Production",
"Experimental",
"Deprecated"
],
"enumColors": {
"Production": "green",
"Experimental": "yellow",
"Deprecated": "red"
},
"icon": "DefaultProperty"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {},
"relations": {}
}
```
</details>

:::note Adding More Blueprint Properties
While this example shows a standard service schema, you can easily add new properties to the blueprint JSON schema to represent additional details about your services and sync them to incident.io.
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {},
"relations": {}
}
```
</details>

5. Click `Save` to create the blueprint.

:::tip Customizing Your Blueprint
This example shows a basic service schema. You can customize it by:
1. **Adding properties**: Add new properties to the `properties` section in the blueprint JSON
2. **Updating the workflow**: Modify the GitHub workflow to include your new properties in the mapping section
3. **Updating incident.io**: Add corresponding attributes in your incident.io catalog type

For example, to add a `team` property, you would:
- Add it to the blueprint JSON properties
- Add the mapping in the workflow (step 4 in the workflow section)
- Add a `team` attribute in incident.io catalog type
:::

## Create a catalog type in incident.io
Expand All @@ -135,30 +158,41 @@ To sync your Port services into incident.io, you first need to create a catalog
- `lifecycle`: Select `string` as the data type
- `type`: Select `string` as the data type

5. Once successful, click on the newly created type and take note of the ID from the browser's URL. For example, the ID might be something like `01J5RB95K5NNDE1CRQ7ZQ24YH5` for this browser URL (https://app.incident.io/organization/catalog/01J5RB95K5NNDE1CRQ7ZQ24YH5). Create a GitHub secret (`INCIDENT_IO_CATALOG_TYPE_ID`) in the repository with the value of this ID.
5. **Save the changes** by clicking the **Save** button
6. Once successful, click on the newly created type and take note of the ID from the browser's URL. For example, the ID might be something like `01J5RB95K5NNDE1CRQ7ZQ24YH5` for this browser URL (https://app.incident.io/organization/catalog/01J5RB95K5NNDE1CRQ7ZQ24YH5)
7. Create a GitHub secret (`INCIDENT_IO_CATALOG_TYPE_ID`) in the repository with the value of this ID


## Create GitHub workflow

Let's go ahead and create a GitHub workflow file in a GitHub repository meant for the incident.io integration:
Let's create a GitHub workflow file in a GitHub repository for the incident.io integration:

- Create a GitHub repository (or use an existing one)
- Create a `.github` directory and `workflows` sub directory

Inside the `.github/workflows` directory create a file called `sync-port-services-to-incident-io.yml` with the following content:

<details>
<summary><b> GitHub workflow configuration (click to expand) </b></summary>
<summary><b>GitHub workflow configuration (click to expand)</b></summary>

:::info Blueprint Schema Matching
Make sure the property names in your Port Service blueprint match the attribute names in your incident.io catalog type. The workflow maps these properties:
- `url` → `url` attribute
- `readme` → `readme` attribute
- `language` → `language` attribute
- `lifecycle` → `lifecycle` attribute
- `type` → `type` attribute

:::tip schedule interval
The default syncing interval is set to 2 hours. Adjust it to suit your use case
If you have different property names, update the mapping in step 4 of the workflow.
:::

```yml showLineNumbers
name: Sync Data to incident.io
on:
schedule:
- cron: "0 */2 * * *" # every two hours. Adjust this value
workflow_dispatch: # allows manual triggering

jobs:
sync-data:
runs-on: ubuntu-latest
Expand Down Expand Up @@ -208,8 +242,8 @@ jobs:
run: |
schema=$(jq '.catalog_type.schema.attributes' schema.json)

# Extract IDs of incident.io catalog attributes. Note that additional properties can be added if needed

# Extract IDs of incident.io catalog attributes
# IMPORTANT: Make sure these attribute names match your incident.io catalog type
url_id=$(echo "$schema" | jq -r '.[] | select(.name == "url") | .id')
readme_id=$(echo "$schema" | jq -r '.[] | select(.name == "readme") | .id')
language_id=$(echo "$schema" | jq -r '.[] | select(.name == "language") | .id')
Expand Down Expand Up @@ -262,27 +296,39 @@ jobs:
-H "Content-Type: application/json" \
-d "$data")

echo "Response from Incident.io API for entity $name"
echo "Incident.io API response for entity $name:"
echo "$response"

# Check if the response indicates success
if echo "$response" | grep -q "201\|200"; then
echo "✅ Successfully synced entity $name to incident.io"
else
echo "❌ Failed to sync entity $name to incident.io"
echo "Response: $response"
fi
done
```

<PortApiRegionTip/>
</details>


## Results
## Let's test it!

Once the scheduled GitHub workflow is triggered, the service entities from Port will be automatically synced into your incident.io catalog. To view the ingested catalog items:
1. **Manual Testing**: Go to your GitHub repository's **Actions** tab and manually trigger the `Sync Data to incident.io` workflow to test it immediately.
2. **Check the logs**: Review the workflow logs to ensure all entities are being synced successfully.
3. **Verify in incident.io**:
- Log in to your incident.io account.
- Navigate to the **Catalog** section in the left navigation bar.
- Search for the `Port Services` catalog type or any custom name you provided.
- You should now see the synced service entities from Port listed under this catalog type.

1. Log in to your incident.io account.
2. Navigate to the **Catalog** section in the left navigation bar.
3. Search for the `Port Services` catalog type or any custom name you provided.
4. You should now see the synced service entities from Port listed under this catalog type, giving you improved visibility and context for managing incidents.
<img src="/img/guides/IncidentioServiceCatalog.png" border="1px" />

<img src="/img/guides/IncidentioServiceCatalog.png" border="1px" />
Once the GitHub workflow runs (either manually or on schedule), the service entities from Port will be automatically synced into your incident.io catalog, giving you improved visibility and context for managing incidents.

With this integration in place, you'll have real-time access to your Port services within incident.io, streamlining your incident response and management processes.

With this integration in place, you’ll have real-time access to your Port services within incident.io, streamlining your incident response and management processes.

## Limitations

Expand Down