Skip to content

Update Humanitec integration docs to contain newly supported resources #2502

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.

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 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
34 changes: 30 additions & 4 deletions docs/guides/all/humanitec-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,21 @@ import HumanitecExporterMainScript from "/docs/guides/templates/humanitec/_human
import HumanitecExporterRequirements from "/docs/guides/templates/humanitec/_humanitec_exporter_requirements.mdx";
import HumanitecExporterPortClient from "/docs/guides/templates/humanitec/_humanitec_exporter_port_client.mdx";
import HumanitecExporterHumanitecClient from "/docs/guides/templates/humanitec/_humanitec_exporter_humanitec_client.mdx";
import HumanitecGroups from "/docs/guides/templates/humanitec/_humanitec_groups.mdx";
import HumanitecUsers from "/docs/guides/templates/humanitec/_humanitec_users.mdx";
import HumanitecPipelines from "/docs/guides/templates/humanitec/_humanitec_pipelines.mdx";
import HumanitecDeploymentDeltas from "/docs/guides/templates/humanitec/_humanitec_deployment_deltas.mdx";
import HumanitecDeploymentSets from "/docs/guides/templates/humanitec/_humanitec_deployment_sets.mdx";
import HumanitecSecretStores from "/docs/guides/templates/humanitec/_humanitec_secret_stores.mdx";
import HumanitecValueSetVersions from "/docs/guides/templates/humanitec/_humanitec_value_set_versions.mdx";
import HumanitecSharedValues from "/docs/guides/templates/humanitec/_humanitec_shared_values.mdx";


# Humanitec Integration

## Overview

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
In this example, you are going 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

:::info Prerequisites
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove this prerequisite as it's not needed here.
Let's move it to the part we set up the GitHub workflow, it can be under a header as add GitHub secretes.
You can check sample guides that implement a Github workflow for example this one acknowledge incident


Expand All @@ -31,7 +40,7 @@ In this example, you are going to create a github worklow integration to facilit
- `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).
:::

## Port blueprints
## Set up data model

Create the following blueprint definitions in port:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's add the steps in creating blueprints here:
`1. Go to the Builder page of your portal.

  1. Click on + Blueprint.

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

  3. Add the JSON schemas:`


Expand All @@ -45,6 +54,23 @@ Create the following blueprint definitions in port:

<HumanitecResourceBlueprint/>

<HumanitecSecretStores/>

<HumanitecSharedValues/>

<HumanitecValueSetVersions/>

<HumanitecDeploymentSets/>

<HumanitecPipelines/>

<HumanitecDeploymentDeltas/>

<HumanitecUsers/>

<HumanitecGroups/>


:::tip Blueprint Properties
You may select the blueprints depending on what you want to track in your Humanitec account.
:::
Expand All @@ -54,7 +80,7 @@ You may select the blueprints depending on what you want to track in your Humani
:::tip
Fork our [humanitec integration repository](https://github.com/port-labs/humanitec-integration-script.git) to get started.
:::
1. Create the following Python files in a folder name `integration` folder at the root of your GitHub repository:
1. Create the following Python files in a folder named `integration` at the base directory of your GitHub repository:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Create the following Python files in a folder named `integration` at the base directory of your GitHub repository:
1. Create the following Python files in a folder named `integration` at the base directory of your GitHub repository:

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The order here doesn't really matter so we can use unordered list here to make it more visually appealing.
The numbered list in a numbered list makes it hard to read

Suggested change
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.
- `main.py` - Orchestrates the synchronization of data from Humanitec to Port, ensuring that resource entities are accurately mirrored and updated on your port catalog.

2. `requirements.txt` - This file contains the dependencies or necessary external packages need to run the integration
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. `requirements.txt` - This file contains the dependencies or necessary external packages need to run the integration
- `requirements.txt` - This file contains the dependencies or necessary external packages need to run the integration


Expand Down Expand Up @@ -146,5 +172,5 @@ jobs:
</details>


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

59 changes: 59 additions & 0 deletions docs/guides/templates/humanitec/_humanitec_deployment_deltas.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
<details>
<summary>Humanitec Deployment Deltas</summary>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<summary>Humanitec Deployment Deltas</summary>
<summary><b>Humanitec deployment deltas (click to expand)</b></summary>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's do same for the others


```json showLineNumbers
{
"identifier": "humanitecDeploymentDelta",
"title": "Humanitec Deployment Delta",
"icon": "Deployment",
"schema": {
"properties": {
"status": {
"title": "Status",
"description": "The status of the deployment delta",
"type": "string",
"icon": "DefaultProperty"
},
"createdAt": {
"title": "Created At",
"description": "The date and time when the deployment delta was created",
"type": "string",
"format": "date-time",
"icon": "DefaultProperty"
},
"createdBy": {
"title": "Created By",
"description": "The user who created the deployment delta",
"type": "string",
"icon": "DefaultProperty"
},
"comment": {
"title": "Comment",
"description": "Comment for the deployment delta",
"type": "string",
"icon": "DefaultProperty"
},
"environment": {
"title": "Environment",
"description": "The environment for the deployment delta",
"type": "string",
"icon": "DefaultProperty"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {},
"relations": {
"humanitecApplication": {
"title": "Application",
"target": "humanitecApplication",
"required": false,
"many": false
}
}
}
```

</details>
53 changes: 53 additions & 0 deletions docs/guides/templates/humanitec/_humanitec_deployment_sets.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
<details>
<summary>Humanitec Deployment Sets</summary>

```json showLineNumbers
{
"identifier": "humanitecDeploymentSet",
"title": "Humanitec Deployment Set",
"icon": "Deployment",
"schema": {
"properties": {
"version": {
"title": "Version",
"description": "The version of the deployment set",
"type": "string",
"icon": "DefaultProperty"
},
"createdAt": {
"title": "Created At",
"description": "The date and time when the deployment set was created",
"type": "string",
"format": "date-time",
"icon": "DefaultProperty"
},
"createdBy": {
"title": "Created By",
"description": "The user who created the deployment set",
"type": "string",
"icon": "DefaultProperty"
},
"comment": {
"title": "Comment",
"description": "Comment for the deployment set",
"type": "string",
"icon": "DefaultProperty"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {},
"relations": {
"humanitecApplication": {
"title": "Application",
"target": "humanitecApplication",
"required": false,
"many": false
}
}
}
```

</details>
Loading