Skip to content

Commit 5d9156e

Browse files
hadar-cohadar-co
authored
Merge pull request #2759 from port-labs/PORT-11540-bug-incident-io-integration-guide-issues
Update sync-service-entities-to-incident-io.md
2 parents 5748c86 + 102d48e commit 5d9156e

File tree

1 file changed

+56
-115
lines changed

1 file changed

+56
-115
lines changed

‎docs/guides/all/sync-service-entities-to-incident-io.md‎

Lines changed: 56 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
sidebar_position: 8
33
displayed_sidebar: null
4-
description: Learn how to sync your Port service entities into incident.io catalog.
4+
description: Learn how to sync your Port service entities into incident.io catalog for better visibility.
55
---
66

77
import Tabs from "@theme/Tabs"
@@ -12,110 +12,28 @@ import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_expl
1212
# Sync Port Services to incident.io
1313
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.
1414

15-
1615
## Prerequisites
1716

18-
- You need a Port account and should have completed the [onboarding process](/getting-started/overview)
19-
- A GitHub repository where you can trigger a workflow for this guide
20-
- An [incident.io](https://app.incident.io/) account and an API key
21-
22-
## Set up required secrets and permissions
17+
- Complete the [onboarding process](/getting-started/overview).
18+
- A GitHub repository where you can trigger a workflow for this guide.
19+
- An [incident.io](https://app.incident.io/) account with **admin access** to create API keys.
20+
- [Port's GitHub app](https://github.com/apps/getport-io) needs to be installed (required for GitHub Actions implementation)
21+
- A `Service` blueprint in Port to represent the service entities you want to sync to incident.io. You should already have one installed during the [onboarding process](/getting-started/overview).
2322

24-
- 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:
25-
- `PORT_CLIENT_ID` - Port Client ID [learn more](/build-your-software-catalog/custom-integration/api/#get-api-token)
26-
- `PORT_CLIENT_SECRET` - Port Client Secret [learn more](/build-your-software-catalog/custom-integration/api/#get-api-token)
27-
- `INCIDENT_IO_API_KEY` - [API key](https://app.incident.io/settings/api-keys) from your incident.io dashboard with the following permissions:
28-
- `Can manage catalog types and edit catalog data`
29-
- `Can view catalog types and entries`
30-
- `INCIDENT_IO_CATALOG_TYPE_ID` - Incident.io catalog type ID. To be created in [this section](#create-a-catalog-item-in-incident-io)
23+
:::info Admin Access Required
24+
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.
25+
:::
3126

27+
## Set up required secrets and permissions
3228

33-
Below is the JSON for the `Service` blueprint that represents the service entities you will sync from Port to incident.io:
29+
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:
30+
- `PORT_CLIENT_ID` - Port Client ID [learn more](/build-your-software-catalog/custom-integration/api/#get-api-token).
31+
- `PORT_CLIENT_SECRET` - Port Client Secret [learn more](/build-your-software-catalog/custom-integration/api/#get-api-token).
32+
- `INCIDENT_IO_API_KEY` - [API key](https://app.incident.io/settings/api-keys) from your incident.io dashboard with the following permissions:
33+
- `Can manage catalog types and edit catalog data`
34+
- `Can view catalog types and entries`
35+
- `INCIDENT_IO_CATALOG_TYPE_ID` - Incident.io catalog type ID. To be created in [this section](#create-a-catalog-type-in-incident-io).
3436

35-
<details>
36-
<summary><b>Service blueprint (click to expand)</b></summary>
37-
38-
```json showLineNumbers
39-
{
40-
"identifier": "service",
41-
"title": "Service",
42-
"icon": "Github",
43-
"schema": {
44-
"properties": {
45-
"readme": {
46-
"title": "README",
47-
"type": "string",
48-
"format": "markdown",
49-
"icon": "Book"
50-
},
51-
"url": {
52-
"title": "URL",
53-
"format": "url",
54-
"type": "string",
55-
"icon": "Link"
56-
},
57-
"language": {
58-
"icon": "Git",
59-
"type": "string",
60-
"title": "Language",
61-
"enum": [
62-
"GO",
63-
"Python",
64-
"Node",
65-
"React"
66-
],
67-
"enumColors": {
68-
"GO": "red",
69-
"Python": "green",
70-
"Node": "blue",
71-
"React": "yellow"
72-
}
73-
},
74-
"type": {
75-
"title": "Type",
76-
"description": "This service's type",
77-
"type": "string",
78-
"enum": [
79-
"Backend",
80-
"Frontend",
81-
"Library"
82-
],
83-
"enumColors": {
84-
"Backend": "purple",
85-
"Frontend": "pink",
86-
"Library": "green"
87-
},
88-
"icon": "DefaultProperty"
89-
},
90-
"lifecycle": {
91-
"title": "Lifecycle",
92-
"type": "string",
93-
"enum": [
94-
"Production",
95-
"Experimental",
96-
"Deprecated"
97-
],
98-
"enumColors": {
99-
"Production": "green",
100-
"Experimental": "yellow",
101-
"Deprecated": "red"
102-
},
103-
"icon": "DefaultProperty"
104-
}
105-
},
106-
"required": []
107-
},
108-
"mirrorProperties": {},
109-
"calculationProperties": {},
110-
"aggregationProperties": {},
111-
"relations": {}
112-
}
113-
```
114-
</details>
115-
116-
:::note Adding More Blueprint Properties
117-
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.
118-
:::
11937

12038
## Create a catalog type in incident.io
12139

@@ -135,30 +53,41 @@ To sync your Port services into incident.io, you first need to create a catalog
13553
- `lifecycle`: Select `string` as the data type
13654
- `type`: Select `string` as the data type
13755

138-
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.
56+
5. **Save the changes** by clicking the **Save** button
57+
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)
58+
7. Create a GitHub secret (`INCIDENT_IO_CATALOG_TYPE_ID`) in the repository with the value of this ID
13959

14060

14161
## Create GitHub workflow
14262

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

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

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

15070
<details>
151-
<summary><b> GitHub workflow configuration (click to expand) </b></summary>
71+
<summary><b>GitHub workflow configuration (click to expand)</b></summary>
15272

153-
:::tip schedule interval
154-
The default syncing interval is set to 2 hours. Adjust it to suit your use case
73+
:::info Blueprint Schema Matching
74+
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:
75+
- `url` → `url` attribute
76+
- `readme` → `readme` attribute
77+
- `language` → `language` attribute
78+
- `lifecycle` → `lifecycle` attribute
79+
- `type` → `type` attribute
80+
81+
If you have different property names, update the mapping in step 4 of the workflow.
15582
:::
15683

15784
```yml showLineNumbers
15885
name: Sync Data to incident.io
15986
on:
16087
schedule:
16188
- cron: "0 */2 * * *" # every two hours. Adjust this value
89+
workflow_dispatch: # allows manual triggering
90+
16291
jobs:
16392
sync-data:
16493
runs-on: ubuntu-latest
@@ -208,8 +137,8 @@ jobs:
208137
run: |
209138
schema=$(jq '.catalog_type.schema.attributes' schema.json)
210139
211-
# Extract IDs of incident.io catalog attributes. Note that additional properties can be added if needed
212-
140+
# Extract IDs of incident.io catalog attributes
141+
# IMPORTANT: Make sure these attribute names match your incident.io catalog type
213142
url_id=$(echo "$schema" | jq -r '.[] | select(.name == "url") | .id')
214143
readme_id=$(echo "$schema" | jq -r '.[] | select(.name == "readme") | .id')
215144
language_id=$(echo "$schema" | jq -r '.[] | select(.name == "language") | .id')
@@ -262,27 +191,39 @@ jobs:
262191
-H "Content-Type: application/json" \
263192
-d "$data")
264193
265-
echo "Response from Incident.io API for entity $name"
194+
echo "Incident.io API response for entity $name:"
195+
echo "$response"
196+
197+
# Check if the response indicates success
198+
if echo "$response" | grep -q "201\|200"; then
199+
echo "✅ Successfully synced entity $name to incident.io"
200+
else
201+
echo "❌ Failed to sync entity $name to incident.io"
202+
echo "Response: $response"
203+
fi
266204
done
267205
```
268206
269207
<PortApiRegionTip/>
270208
</details>
271209
272210
273-
## Results
211+
## Let's test it!
274212
275-
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:
213+
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.
214+
2. **Check the logs**: Review the workflow logs to ensure all entities are being synced successfully.
215+
3. **Verify in incident.io**:
216+
- Log in to your incident.io account.
217+
- Navigate to the **Catalog** section in the left navigation bar.
218+
- Search for the `Port Services` catalog type or any custom name you provided.
219+
- You should now see the synced service entities from Port listed under this catalog type.
276220

277-
1. Log in to your incident.io account.
278-
2. Navigate to the **Catalog** section in the left navigation bar.
279-
3. Search for the `Port Services` catalog type or any custom name you provided.
280-
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.
221+
<img src="/img/guides/IncidentioServiceCatalog.png" border="1px" />
281222

282-
<img src="/img/guides/IncidentioServiceCatalog.png" border="1px" />
223+
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.
283224

225+
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.
284226

285-
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.
286227

287228
## Limitations
288229

0 commit comments

Comments
 (0)