You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -15,98 +15,152 @@ import HumanitecExporterMainScript from "/docs/guides/templates/humanitec/_human
15
15
import HumanitecExporterRequirements from "/docs/guides/templates/humanitec/_humanitec_exporter_requirements.mdx";
16
16
import HumanitecExporterPortClient from "/docs/guides/templates/humanitec/_humanitec_exporter_port_client.mdx";
17
17
import HumanitecExporterHumanitecClient from "/docs/guides/templates/humanitec/_humanitec_exporter_humanitec_client.mdx";
18
+
import HumanitecGroups from "/docs/guides/templates/humanitec/_humanitec_groups.mdx";
19
+
import HumanitecUsers from "/docs/guides/templates/humanitec/_humanitec_users.mdx";
20
+
import HumanitecPipelines from "/docs/guides/templates/humanitec/_humanitec_pipelines.mdx";
21
+
import HumanitecDeploymentDeltas from "/docs/guides/templates/humanitec/_humanitec_deployment_deltas.mdx";
22
+
import HumanitecDeploymentSets from "/docs/guides/templates/humanitec/_humanitec_deployment_sets.mdx";
23
+
import HumanitecSecretStores from "/docs/guides/templates/humanitec/_humanitec_secret_stores.mdx";
24
+
import HumanitecValueSetVersions from "/docs/guides/templates/humanitec/_humanitec_value_set_versions.mdx";
25
+
import HumanitecSharedValues from "/docs/guides/templates/humanitec/_humanitec_shared_values.mdx";
26
+
18
27
19
28
# Humanitec Integration
20
29
21
-
## Overview
30
+
This guide demonstrates how to create a GitHub worklow integration to facilitate the ingestion of Humanitec applications, environments, workloads, resources, resource graphs, pipelines, deployment deltas, deployment sets, secret stores, shared values, value set versions, users, groups into your Port catalog on schedule.
22
31
23
-
In this example, you are going to create a github worklow integration to facilitate the ingestion of Humanitec applications, environments, workloads, resources and resource graphs into your port catalog on schedule
1. 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:
28
-
-`HUMANITEC_API_KEY` - [Humanitec API Key](https://developer.humanitec.com/platform-orchestrator/reference/api-references/#authentication)
-`PORT_CLIENT_ID` - Your port `client id`[How to get the credentials](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/api/#find-your-port-credentials).
31
-
-`PORT_CLIENT_SECRET` - Your port `client secret`[How to get the credentials](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/api/#find-your-port-credentials).
32
-
:::
36
+
- Empower platform teams to gain visibility and advanced insights into your Humanitec entities including application, environments, users, and groups from Port among other entities.
37
+
- Track the status of changes to your Humanitec entities from Port.
38
+
- Prepare your Port environment to build useful experiences for Platform Engineering teams with Self Service Actions.
39
+
40
+
## Prerequisites
41
+
42
+
This guide assumes the following:
43
+
- You have a Port account and have completed the [onboarding process](https://docs.port.io/getting-started/overview).
44
+
- You have a Humanitec account and a [Service User created](https://developer.humanitec.com/platform-orchestrator/docs/platform-orchestrator/security/service-users/) (You need an Administrator or Manager privilege to create a Service User).
45
+
- You have a GitHub account and a repository.
46
+
47
+
48
+
## Set up data model
49
+
50
+
As a first step, you need to create blueprint definitions in Port for the Humanitec entities you want to ingest. To do this follow the steps below:
51
+
52
+
1. Go to the [Builder](https://app.getport.io/settings/data-model/data-model) page in your Port organization.
53
+
2. Click on the **+ Blueprint** button at the top of the page.
54
+
3. Click on `{...} Edit JSON` button at the top right corner.
55
+
4. Copy and paste the following blueprint JSON into the editor, repeating the process for each blueprint:
56
+
57
+
<HumanitecApplicationBlueprint/>
58
+
59
+
<HumanitecEnvironmentBlueprint/>
33
60
34
-
## Port blueprints
61
+
<HumanitecWorkloadBlueprint/>
35
62
36
-
Create the following blueprint definitions in port:
63
+
<HumanitecResourceGraphBlueprint/>
37
64
38
-
<HumanitecApplicationBlueprint/>
65
+
<HumanitecResourceBlueprint/>
39
66
40
-
<HumanitecEnvironmentBlueprint/>
67
+
<HumanitecSecretStores/>
41
68
42
-
<HumanitecWorkloadBlueprint/>
69
+
<HumanitecSharedValues/>
43
70
44
-
<HumanitecResourceGraphBlueprint/>
71
+
<HumanitecValueSetVersions/>
72
+
73
+
<HumanitecDeploymentSets/>
74
+
75
+
<HumanitecPipelines/>
76
+
77
+
<HumanitecDeploymentDeltas/>
78
+
79
+
<HumanitecUsers/>
80
+
81
+
<HumanitecGroups/>
45
82
46
-
<HumanitecResourceBlueprint/>
47
83
48
84
:::tip Blueprint Properties
49
85
You may select the blueprints depending on what you want to track in your Humanitec account.
50
86
:::
51
87
52
-
## GitHub Workflow
88
+
## Set up the integration
53
89
54
-
:::tip
55
90
Fork our [humanitec integration repository](https://github.com/port-labs/humanitec-integration-script.git) to get started.
56
-
:::
57
-
1. Create the following Python files in a folder name `integration` folder at the root of your GitHub repository:
58
-
1.`main.py` - Orchestrates the synchronization of data from Humanitec to Port, ensuring that resource entities are accurately mirrored and updated on your port catalog.
59
-
2.`requirements.txt` - This file contains the dependencies or necessary external packages need to run the integration
60
-
61
-
<details>
62
-
<summary>Main Executable Script</summary>
63
91
64
-
<HumanitecExporterMainScript/>
65
92
66
-
</details>
93
+
### Add secrets to your GitHub repository
67
94
68
-
<details>
69
-
<summary>Requirements</summary>
95
+
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:
96
+
-`HUMANITEC_API_KEY` - [Humanitec API Key](https://developer.humanitec.com/platform-orchestrator/docs/platform-orchestrator/security/service-users/#generate-an-api-token-from-a-service-user)
-`PORT_CLIENT_ID` - Your Port `client id`[How to get the credentials](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/api/#find-your-port-credentials).
99
+
-`PORT_CLIENT_SECRET` - Your Port `client secret`[How to get the credentials](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/api/#find-your-port-credentials).
70
100
71
-
<HumanitecExporterRequirements/>
72
101
73
-
</details>
102
+
### Create the Python files
103
+
104
+
1. Create the following Python files in a folder named `integration` at the base directory of your GitHub repository:
105
+
-`main.py` - Orchestrates the synchronization of data from Humanitec to Port, ensuring that resource entities are accurately mirrored and updated on your Port catalog.
106
+
-`requirements.txt` - This file contains the dependencies or necessary external packages need to run the integration
107
+
108
+
109
+
110
+
<details>
111
+
<summary><b>Main Executable Script (Click to expand)</b></summary>
112
+
113
+
<HumanitecExporterMainScript/>
114
+
115
+
</details>
116
+
117
+
118
+
<details>
119
+
<summary><b>Requirements (Click to expand)</b></summary>
120
+
121
+
<HumanitecExporterRequirements/>
122
+
123
+
</details>
124
+
74
125
75
126
2. Create the following Python files in a folder named `clients` at the base directory of the `integration` folder:
76
-
1.`port_client.py` – Manages authentication and API requests to Port, facilitating the creation and updating of entities within Port's system.
77
-
2.`humanitec_client.py` – Handles API interactions with Humanitec, including retrieving data with caching mechanisms to optimize performance.
78
-
3.`cache.py` - Provides an in-memory caching mechanism with thread-safe operations for setting, retrieving, and deleting cache entries asynchronously.
127
+
-`port_client.py` – Manages authentication and API requests to Port, facilitating the creation and updating of entities within Port's system.
128
+
-`humanitec_client.py` – Handles API interactions with Humanitec, including retrieving data with caching mechanisms to optimize performance.
129
+
-`cache.py` - Provides an in-memory caching mechanism with thread-safe operations for setting, retrieving, and deleting cache entries asynchronously.
79
130
80
-
<details>
81
-
<summary>Port Client</summary>
131
+
<details>
132
+
<summary><b>Port Client (Click to expand)</b></summary>
82
133
83
-
<HumanitecExporterPortClient/>
134
+
<HumanitecExporterPortClient/>
84
135
85
-
</details>
136
+
</details>
86
137
87
-
<details>
88
-
<summary>Humanitec Client</summary>
138
+
<details>
139
+
<summary><b>Humanitec Client (Click to expand)</b></summary>
89
140
90
-
<HumanitecExporterHumanitecClient/>
141
+
<HumanitecExporterHumanitecClient/>
91
142
92
-
</details>
143
+
</details>
93
144
94
145
95
-
<details>
96
-
<summary>Cache</summary>
146
+
<details>
147
+
<summary><b>Cache (Click to expand)</b></summary>
97
148
98
-
<HumanitecExporterCacheScript/>
149
+
<HumanitecExporterCacheScript/>
99
150
100
-
</details>
151
+
</details>
101
152
102
-
3. Create the file `.github/workflows/humanitec-exporter.yaml` in the `.github/workflows` folder of your repository.
153
+
### Create the GitHub workflow
154
+
155
+
Create the file `.github/workflows/humanitec-exporter.yaml` in the `.github/workflows` folder of your repository.
103
156
104
157
:::tip Cron
105
158
Adjust the cron expression to fit your schedule. By default, the workflow is set to run at 2:00 AM every Monday ('0 2 * * 1').
106
159
:::
107
160
161
+
108
162
<details>
109
-
<summary>GitHub Workflow</summary>
163
+
<summary><b>GitHub Workflow (Click to expand)</b></summary>
Done! Any change that happens to your application, environment, workloads or resources in Humanitec will be synced to Port on the schedule interval defined in the GitHub workflow.
203
+
Done! Any change that happens to your application, environment, workloads, resources, resource graphs, pipelines, deployment deltas, deployment sets, secret stores, shared values, value set versions, users, groups in Humanitec will be synced to Port on the schedule interval defined in the GitHub workflow.
0 commit comments