diff --git a/docs/internal-developer-portal/catalog/catalog-yaml.md b/docs/internal-developer-portal/catalog/catalog-yaml.md index 8aebf9bf1ab..0bb3ca32485 100644 --- a/docs/internal-developer-portal/catalog/catalog-yaml.md +++ b/docs/internal-developer-portal/catalog/catalog-yaml.md @@ -121,6 +121,32 @@ metadata: ``` +
+User Group YAML Example + +```yaml +apiVersion: harness.io/v1 +kind: Group +type: engineering +name: Cloud Infrastructure Team +identifier: cloud_infrastructure_team +spec: + members: + - user:account/jane.doe@harness.io + - user:account/john.smith@harness.io + parent: group:account/idp_team + profile: + email: cloud_infrastructure_team@techo.io +metadata: + description: User Group responsible for building and maintaining the company’s core cloud infrastructure. + teamLead: Jane Doe + region: US West + tags: + - cloud + - engineering +``` +
+ :::info Please ensure that **no entity YAML files** are stored in **Git in IDP 2.0** until the [Git Experience](/docs/internal-developer-portal/idp-2o-overview/2-0-overview-and-upgrade-path.md#native-harness-git-experience) feature is released. You can track its release and other updates in the **[IDP 2.0 Features Status](/docs/internal-developer-portal/idp-2o-overview/2-0-overview-and-upgrade-path.md)** table ::: @@ -205,6 +231,7 @@ With **IDP 2.0**, you can define the following `kind` types in your Catalog YAML * `kind: Resource` * `kind: Workflow` * `kind: System` +* `kind: Group` Each kind represents a different type of entity within the Harness-native data model. [Read more about the different entity kinds here.](/docs/internal-developer-portal/catalog/catalog-yaml.md#entity-kinds) @@ -507,6 +534,56 @@ metadata: --- +### Kind: Group +**Group** entities allow organizations to model their team structure directly within the IDP catalog. Custom User Groups extend the catalog model to include organizational teams and hierarchies as first-class entities, representing real-world structures such as teams, departments, or cross-functional squads. + +Unlike platform user groups which are synchronized from an identity provider (LDAP, SCIM, SSO), custom user groups are created and managed entirely within IDP, allowing for richer metadata and context. + +#### Entity Structure +All the fields mentioned below are the parameters required to define a Group: + +| **Field** | **Value** | +| --------- | --------- | +| `apiVersion` | **harness.io/v1** | +| `kind` | **Group** | +| `name` | Human-readable name for the group | +| `identifier` | Unique identifier for the group | +| `type` | Common values include `department`, `engineering` | + +#### Special Spec Fields + +| **Field** | **Description** | +| --------- | --------------- | +| `spec.members` | List of users belonging to the group | +| `spec.parent` | Reference to a parent group, enabling hierarchy | +| `spec.profile` | Additional profile information like email | + +#### Example YAML +```yaml +apiVersion: harness.io/v1 +kind: Group +type: engineering +name: Cloud Infrastructure Team +identifier: cloud_infrastructure_team +spec: + members: + - user:account/jane.doe@harness.io + - user:account/john.smith@harness.io + lifecycle: active + parent: group:account/idp_team + profile: + email: idp_team@harness.io +metadata: + description: Cloud Infrastructure Team for building and maintaining the company’s core cloud infrastructure. + teamLead: Jane Doe + region: US West + tags: + - cloud + - engineering +``` + +--- + ### Kind: Workflow **Workflows** enable developer self-service by automating manual tasks and processes. Platform engineering teams can use workflows to: - Automate new service onboarding @@ -1047,7 +1124,12 @@ The current set of well-known and common values for this field is: #### Spec owner -In the Harness Internal Developer Portal, the owner of a component is identified by the [Harness User Group ID](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups). This User Group ID represents the collective entity that holds ultimate responsibility for the component and possesses the authority and capability to develop and maintain it. Should any issues arise or if there are requests for features, this User Group will serve as the primary point of contact. The primary purpose of this field in the Harness IDP is for display, ensuring that individuals accessing catalog items can easily identify the responsible User Group for a given component. +In the Harness Internal Developer Portal, the owner of a component can be identified by either: + +* **Platform User Group ID**: The [Harness User Group ID](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups) for groups synced from identity providers +* **Custom User Group** [IDP 2.0]: A [Custom User Group](/docs/internal-developer-portal/catalog/user-group) created directly within IDP as a first-class catalog entity + +In both cases, this User Group represents the collective entity that holds ultimate responsibility for the component and possesses the authority and capability to develop and maintain it. Should any issues arise or if there are requests for features, this User Group will serve as the primary point of contact. The primary purpose of this field in the Harness IDP is for display, ensuring that individuals accessing catalog items can easily identify the responsible User Group for a given component.
How to get the Harness User Group ID diff --git a/docs/internal-developer-portal/catalog/content/user-group/static/additionalinfocard.png b/docs/internal-developer-portal/catalog/content/user-group/static/additionalinfocard.png new file mode 100644 index 00000000000..f058b04c058 Binary files /dev/null and b/docs/internal-developer-portal/catalog/content/user-group/static/additionalinfocard.png differ diff --git a/docs/internal-developer-portal/catalog/content/user-group/static/child-parent.png b/docs/internal-developer-portal/catalog/content/user-group/static/child-parent.png new file mode 100644 index 00000000000..7d9fd215a77 Binary files /dev/null and b/docs/internal-developer-portal/catalog/content/user-group/static/child-parent.png differ diff --git a/docs/internal-developer-portal/catalog/content/user-group/static/create-usergroup.png b/docs/internal-developer-portal/catalog/content/user-group/static/create-usergroup.png new file mode 100644 index 00000000000..c5e6467c0c0 Binary files /dev/null and b/docs/internal-developer-portal/catalog/content/user-group/static/create-usergroup.png differ diff --git a/docs/internal-developer-portal/catalog/content/user-group/static/duplicate.gif b/docs/internal-developer-portal/catalog/content/user-group/static/duplicate.gif new file mode 100644 index 00000000000..fb55ad68ef9 Binary files /dev/null and b/docs/internal-developer-portal/catalog/content/user-group/static/duplicate.gif differ diff --git a/docs/internal-developer-portal/catalog/content/user-group/static/groups.png b/docs/internal-developer-portal/catalog/content/user-group/static/groups.png new file mode 100644 index 00000000000..836da92538b Binary files /dev/null and b/docs/internal-developer-portal/catalog/content/user-group/static/groups.png differ diff --git a/docs/internal-developer-portal/catalog/content/user-group/static/layout-usergroup.png b/docs/internal-developer-portal/catalog/content/user-group/static/layout-usergroup.png new file mode 100644 index 00000000000..8d955b2bac4 Binary files /dev/null and b/docs/internal-developer-portal/catalog/content/user-group/static/layout-usergroup.png differ diff --git a/docs/internal-developer-portal/catalog/content/user-group/static/overview.png b/docs/internal-developer-portal/catalog/content/user-group/static/overview.png new file mode 100644 index 00000000000..ee8995159b1 Binary files /dev/null and b/docs/internal-developer-portal/catalog/content/user-group/static/overview.png differ diff --git a/docs/internal-developer-portal/catalog/content/user-group/static/team.png b/docs/internal-developer-portal/catalog/content/user-group/static/team.png new file mode 100644 index 00000000000..88789ce4412 Binary files /dev/null and b/docs/internal-developer-portal/catalog/content/user-group/static/team.png differ diff --git a/docs/internal-developer-portal/catalog/content/user-group/static/user-group-overview.png b/docs/internal-developer-portal/catalog/content/user-group/static/user-group-overview.png new file mode 100644 index 00000000000..d259ea1b47c Binary files /dev/null and b/docs/internal-developer-portal/catalog/content/user-group/static/user-group-overview.png differ diff --git a/docs/internal-developer-portal/catalog/add-user-groups-in-catalog.md b/docs/internal-developer-portal/catalog/content/user-group/user-group-idp-1.md similarity index 83% rename from docs/internal-developer-portal/catalog/add-user-groups-in-catalog.md rename to docs/internal-developer-portal/catalog/content/user-group/user-group-idp-1.md index 26c49ab3aae..3a4bf5a064f 100644 --- a/docs/internal-developer-portal/catalog/add-user-groups-in-catalog.md +++ b/docs/internal-developer-portal/catalog/content/user-group/user-group-idp-1.md @@ -1,22 +1,9 @@ ---- -title: How to Add User Groups Directly in the Catalog -description: Detailed instructions on how to add user groups directly into the IDP Catalog -sidebar_label: Ingest User Groups in Catalog -sidebar_position: 10 -redirect_from: - - docs/internal-developer-portal/catalog/add-users-in-catalog ---- - -:::info -This feature is **only available in IDP 1.0**. Custom user groups will be available soon in IDP 2.0. -::: +## Add User Groups Directly in the Catalog The Catalog in Harness IDP also supports addition of [organizational entities](https://backstage.io/docs/features/software-catalog/system-model#organizational-entities) like **user groups** directly, independent of their presence on the Harness Platform. These entities can be registered as `kind: Group` in the catalog as an YAML. Note that our recommendation is to use the [Harness Platform Access Control](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups/) for ingesting Users and User Groups into Harness IDP. :::info - The User Groups registered as entities in Catalog directly are not synced back with Harness Platform. The User Groups you add in IDP won't be available as a [Harness Platform User Group](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups). However, the opposite is true - any user group created in the Harness Platform at the Account level scope will be available in the IDP Catalog as well. - ::: ## Kind: Group @@ -24,9 +11,7 @@ The User Groups registered as entities in Catalog directly are not synced back w A group describes an organizational entity, such as a team, a business unit, or a loose collection of people in an interest group. Members of these groups are modeled in the catalog as User. :::info - You can not add Users directly into the catalog as Users are linked with authentication. You can [add users](https://developer.harness.io/docs/platform/role-based-access-control/add-users/#add-users-manually) on the Harness platform at the Account level. - ::: Descriptor files for this kind may look as follows, where `apiVersion`, `kind`, `spec.type` and `spec.children` are **required** fields. @@ -44,10 +29,9 @@ spec: email: infrastructure@example.com picture: https://example.com/groups/bu-infrastructure.jpeg parent: ops - children: [backstage, other] - members: [jdoe] + children: [infra-devops, infra-devsecops] + members: [mira.rosen, lee.coleman] ``` - In the above example, `children` represent other user-groups and `members` represent the users under this user group. At present we sync all your [user-groups](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups/) added in Harness Platform to IDP and you could find them under catalog page. @@ -64,7 +48,7 @@ In case there's a user-group already present with the same `metadata.name` while ![](./static/team.png) -### When to ingest groups directly into the Catalog rather than creating a Harness Platform User Group at the account level? +#### When to ingest groups directly into the Catalog rather than creating a Harness Platform User Group at the account level? - If you need to represent a Group of Groups kind of hierarchy e.g. Org -> Department -> Team - If you would like the Groups definition to support annotations and tags to be consumed by plugins on the Groups page in Catalog. diff --git a/docs/internal-developer-portal/catalog/content/user-group/user-group-idp-2.md b/docs/internal-developer-portal/catalog/content/user-group/user-group-idp-2.md new file mode 100644 index 00000000000..682d3f35791 --- /dev/null +++ b/docs/internal-developer-portal/catalog/content/user-group/user-group-idp-2.md @@ -0,0 +1,365 @@ +## Custom User Group Entity + +Custom User Groups in Harness IDP extend the catalog model to include organizational teams and hierarchies as **first-class entities**. These groups allow companies to represent real-world structures such as teams, departments, or cross-functional squads, directly inside the developer portal. + +Unlike **[platform user groups](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups/)** which are typically synchronized from an identity provider (LDAP, SCIM, SSO), **custom user groups** are created and managed entirely within IDP. This distinction matters because it allows engineering and platform teams to enrich group definitions with metadata that may not exist in the identity provider but is valuable for context inside IDP. + +## Key Concepts + +**1. Group Entity** + +* Each group is represented as an IDP entity with its own YAML definition. +* A group can include members, a parent relationship,and optional metadata. +* Groups can serve as owners of services, systems, and other catalog entities. + +**2. Parent–Child Hierarchies** + +* Groups support hierarchical relationships (e.g., "Backend Team" as a child of "Engineering Org"). +* Parent groups automatically infer their children; explicit child definitions are not needed. + +**3. Metadata Enrichment** + +* Beyond basic member lists, custom groups can include metadata such as team lead, manager, geographic region, or contact email. +* This metadata can be surfaced in catalog cards, dashboards, and reporting. + +**4. Source of Truth** + +* IDP becomes the **ultimate source of truth** for group modeling. +* Platform-synced groups continue to appear but will not overwrite custom groups if a conflict in identifiers exists. +* This ensures invested effort in creating and enriching groups inside IDP is preserved. + +![user-group-overview](./static/user-group-overview.png) + +## Creating Custom User Groups + +![create-usergroup](./static/create-usergroup.png) +There are two ways to create a group: + +1. **Through the UI** – A guided creation page in the IDP Catalog allows platform engineers or admins to define groups with fields such as members, parent groups, and metadata. Members and parent groups can be added through searchable dropdowns that surface both users and groups. + +2. **Through YAML Definition** – Groups can also be created and registered by authoring YAML. The structure aligns with IDP 2.0's entity model while retaining compatibility with the original Backstage semantics. + +Here is a representative YAML snippet for creating a group: + +```yaml +apiVersion: harness.io/v1 +kind: Group +type: engineering +name: Cloud Infrastructure Team +identifier: cloud_infrastructure_team +spec: + members: + - user:account/alice.chen@techco.com + - user:account/bob.smith@techco.com + parent: group:account/techco + profile: + email: cloud-platform@techco.com +metadata: + tags: + - cloud + - platform + - engineering + description: User Group responsible for building and maintaining the company's core cloud infrastructure. +``` + +This example defines a **Cloud Infrastructure Team** team, scoped at the account level, with two members, a parent group (`techco`), and rich metadata including tags and a description. + +3. **Through the API** – Groups can be created and managed programmatically by crafting YAML definitions with the `kind` set as `Group` and utilizing the [Entity API](https://developer.harness.io/docs/platform/api/entity-api) for creating and updating Group entities. + +:::note +At present, the User Group entity can only be created at the account level. +::: + +#### Key Attributes in Group YAML + +* **apiVersion / kind** – Always `harness.io/v1` and `Group` +* **identifier and name** – Unique reference and display name for the group +* **type** – Arbitrary classification, e.g., `engineering` or `api` +* **spec.members** – List of users belonging to the group +* **spec.parent** – Reference to a parent group, enabling hierarchy +* **metadata** – Arbitrary tags and description for discoverability + +Groups can be created with **zero members**, making it possible to scaffold team structures first and populate them later.- + +## Relationships and Hierarchies + +![child-parent](./static/child-parent.png) + +### Parent and Child Groups + +Groups can be linked together through **hierarchical relationships**. In YAML, the creator specifies only the `parent` field. The IDP ingestion process then automatically generates the inverse relationships (`childOf` and `parentOf`) so that hierarchies are consistent and visible in the Catalog Graph. + +For example: + +```yaml +apiVersion: harness.io/v1 +kind: Group +type: engineering +identifier: cloud_infrastructure_team +name: Cloud Infrastructure Team +spec: + parent: group:account/harness + members: + - user:account/user1@harness.io + - user:account/user2@harness.io +``` + +In this setup: + +* `cloud_infrastructure_team` is explicitly linked to the `harness` group as its parent. +* IDP automatically infers and persists these relationships: + + * `cloud_infrastructure_team → childOf → harness` + * `harness → parentOf → cloud_infrastructure_team` + +This ensures that users see a **two-way relationship** in the Catalog Graph without having to manually declare `children`. + +### User Relationships + +Groups connect to users through **membership relationships**. These are expressed in YAML under `spec.members`. + +Example: + +```yaml +spec: + members: + - user:account/user1@harness.io + - user:account/user2@harness.io +``` + +This creates: + +* `cloud_infrastructure_team → hasMember → user1@harness.io` +* `user1@harness.io → memberOf → cloud_infrastructure_team` + +These relationships are also surfaced in the Catalog Graph, enabling visual exploration of who belongs to which group. + +### Ownership Mapping + +Groups are first-class entities for **owning other Catalog entities**. Ownership is established when a group is referenced in another entity's YAML. + +For example, a service YAML might designate a group as its owner: + +```yaml +apiVersion: harness.io/v1 +kind: Component +identifier: payments_service +name: Payments Service +spec: + type: service + owner: group:account/cloud_infrastructure_team +``` + +This results in: + +* `payments_service → ownedBy → cloud_infrastructure_team` +* `cloud_infrastructure_team → ownerOf → payments_service` + +On the service's Catalog page, the owner group is prominently displayed, making accountability clear. + +:::info User Group Conflict Resolution +Harness IDP allows two sources of User Groups to coexist in the catalog: + +1. **IDP User Groups** - Created directly within IDP (custom user groups) +2. **Platform User Groups** - Synced from the Harness Platform + +When both types of User Groups exist, the following conflict resolution rules apply: + +* **IDP User Groups take precedence over Platform User Groups** - Custom groups created directly in IDP are considered the ultimate source of truth. +* **Identifier conflict handling** - If an IDP User Group and a Platform User Group share the same identifier, the platform user group will not be synced. +* **Precedence order**: + 1. IDP User Groups (directly created) + 2. Platform User Groups (synced from Harness Platform) + +This approach ensures that any custom metadata, relationships, and configurations you've invested time in creating for IDP User Groups are preserved and not overwritten during platform synchronization. +::: +:::note +Information about conflicts may be available in the audit trail. Platform user groups with the same ID as existing IDP User Groups will not be synced, while all other platform groups will continue to be synchronized normally. +::: + +## Find User Groups in the Catalog + +Once created, User Groups are fully discoverable inside the IDP Catalog. You can look them up directly by name or identifier using the catalog search bar. For example, searching for **Cloud Infrastructure Team** quickly brings up the corresponding group entity. + +![overview](./static/overview.png) + +Opening a group shows a detailed **Overview** page: + +* **Profile Information**: Includes the group name, description, type (custom or platform), scope (account, org, or project), and metadata such as email or tags. +* **Relations Panel**: Displays the parent group, child groups, and members connected through the `parentOf`, `childOf`, and `hasMember` relations. This is shown as both a list and an interactive graph. + +![user-group-overview](./static/user-group-overview.png) + + * You can click into related entities (parent group, child group, or member) to navigate further in the catalog. + * For example, the **Cloud Infrastructure Team** group shows its parent **Techo Cloud Team**, two members, and owner of entity **member-service**. +* **Members Section**: Lists all the individual users associated with the group, along with their identifiers and contact details. + +This layout makes it easy for developers, platform engineers, and admins to understand the context of a group at a glance and explore connected entities with just a click. + +## Metadata Enrichment + +Custom User Groups in IDP are not limited to listing members. They can carry **rich metadata** that makes them more useful for discovery, reporting, and ownership tracking. This metadata sits under the `metadata` field in the entity YAML and can include fields such as: + +* **Description** of the group +* **Team Lead** or manager +* **Geographic region** +* **Tags** for classification or filtering +* Any other key-value pairs that make sense for your organization + +Example: + +```yaml +apiVersion: harness.io/v1 +kind: Group +type: engineering +name: Cloud Infrastructure Team +identifier: cloud_infrastructure_team +spec: + lifecycle: "" + parent: group:account/idp_team + members: + - user:account/mabihs.rahd@techco.io + - user:account/arawsengiv.mh@techco.io + profile: + email: cloud-platform@techco.com +metadata: + description: " User Group responsible for building and maintaining the company's core cloud infrastructure." + role: Engineer Manager + region: East Blue + focusarea: Platform + teamlead: Monkey D Luffy + tags: + - cloud + - platform + - engineering +``` + +This metadata can be surfaced in **catalog cards**, **dashboards**, and **reporting views**, giving platform engineers and leadership more context about each group. +For example: a sales engineer could quickly find the right **geo-aligned team**, or a developer could identify the **team lead** directly from the group's catalog page. + +### Additional Infocard + +The `EntityAdditionalInfoCard` component provides a powerful way to surface important metadata from your Custom User Groups directly on their entity pages. This component allows you to selectively display key information about the group in a structured, visually appealing card format. + +Here's how to configure an Additional Infocard that displays leadership and organizational information: + +```yaml +- component: EntityAdditionalInfoCard + specs: + props: + title: Leader Information + items: + - label: Team Leader + value: <+metadata.teamlead> + type: string + style: + bold: true + - label: Focus Area + value: <+metadata.focusarea> + type: string + style: + bold: false + - label: Role + value: <+metadata.role> + type: string + style: + bold: false + - label: Region + value: <+metadata.region> + type: string + style: + bold: false + gridProps: + xs: 12 + md: 6 +``` + +Key features of the `EntityAdditionalInfoCard`: + +- **Custom Title**: Set a meaningful title like "Leader Information" or "Team Details" +- **Dynamic Value Binding**: Use the `<+metadata.fieldname>` syntax to pull values directly from the group's metadata +- **Visual Styling**: Control typography with options like bold text for emphasis on important fields +- **Flexible Layout**: Configure the card's placement and size with grid properties +- **Multiple Cards**: Add several info cards to group related metadata together + +![additionalinfocard](./static/additionalinfocard.png) + +This approach makes important information about the group immediately visible without requiring users to dig through raw YAML or metadata fields. For example, a developer looking at a group page can quickly see who leads the team and what region they operate in, facilitating better communication and collaboration. + +## Configuring the Custom Group Layout in Group Entities + +By default, you won't see any layout for the Custom Group entities, but you can duplicate the layout of the Group entities, IDP provides a standard view for all **Group entities**, showing the profile, members, and graph. However, administrators can customize the layout to highlight the metadata that matters most to their organization. + +You can configure layouts from: +`Admin → Layout → Group Entities` + +Then duplicate an existing laypuit of kind `Group` and you will be asked to providethe type for it. Make sure top provide the type same as for the user group entity you want the layout for. + +![duplicate](./static/duplicate.gif) + +After that you can define what cards and panels appear on the group's entity page. For example, you might want to show the **team lead** or **region** metadata prominently, alongside the member list and hierarchy graph. + +![layout-usergroup](./static/layout-usergroup.png) + +Example configuration: + +```yaml +page: + name: EntityLayout + tabs: + - name: Overview + path: / + title: Overview + contents: + - component: EntityOrphanWarning + - component: EntityProcessingErrorsPanel + - component: EntityGroupProfileCard + specs: + gridProps: + xs: 12 + md: 6 + - component: EntityCatalogGraphCard + specs: + gridProps: + xs: 12 + md: 6 + - component: EntityAdditionalInfoCard + specs: + props: + title: Leader Information + items: + - label: Team Leader + value: <+metadata.teamlead> + type: string + style: + bold: true + - label: Focus Area + value: <+metadata.focusarea> + type: string + style: + bold: false + - label: Role + value: <+metadata.role> + type: string + style: + bold: false + - label: Region + value: <+metadata.region> + type: string + style: + bold: false + gridProps: + xs: 12 + md: 6 + - component: EntityMembersListCard + specs: + gridProps: + xs: 12 + md: 6 +``` + +In this example: + +* The **Group Profile** and **Graph** remain visible for structure and relationships. +* An **Additional Info Card** surfaces metadata fields (`teamlead`, `region`). +* The **Members List** card continues to show assigned users. diff --git a/docs/internal-developer-portal/catalog/data-model.md b/docs/internal-developer-portal/catalog/data-model.md index d5c820398a9..897542fb33b 100644 --- a/docs/internal-developer-portal/catalog/data-model.md +++ b/docs/internal-developer-portal/catalog/data-model.md @@ -31,12 +31,13 @@ Let's dive deeper into how entities and scopes come together in the Harness-nati ## Harness IDP Entities [IDP 2.0] -There are different entities within our Harness IDP data model. However, software is modeled in the Harness IDP Catalog using four core entities: +There are different entities within our Harness IDP data model. However, software is modeled in the Harness IDP Catalog using five core entities: * **Components**: Individual pieces of software. * **APIs**: Boundaries between different components. * **Resources**: Physical or virtual infrastructure needed to operate a component. * **Systems**: High-level organizational units that group related components, APIs and resources. +* **Groups**: Custom user groups representing team structures, departments, or any organizational unit. ![](static/intro-system.png) @@ -81,11 +82,29 @@ For more details on how to use this entity, please refer to the [detailed docs]( ## Harness Platform Entities [IDP 2.0] -We also support Harness Platform Entities - Users and User Groups. +We support both Harness Platform Entities (Users and Platform User Groups) and Custom User Groups created directly within IDP. ### Users -A **User** refers to a person who has been onboarded or has access to any part of Harness IDP. Across Harness, a user is any individual registered with a unique email address. Users can be associated with multiple Harness accounts and can belong to multiple user groups. Roles and resource groups can be assigned directly to users or inherited from user groups. Here's how you can [add users](https://developer.harness.io/docs/platform/role-based-access-control/add-users/) in Harness IDP. +A **User** entity represents a person or an automated account which has authentication details stored. If you have an identity provider configured in your Harness platform, Users from that system would be automatically reflected in the IDP catalog. + +### Platform User Groups + +A **Platform User Group** entity represents a collection of related Users which have authentication details stored and are synchronized from an identity provider (LDAP, SCIM, SSO). These are typically used for role-based access control. + +### Custom User Groups + +New in IDP 2.0, **Custom User Groups** are created and managed entirely within IDP as first-class entities. Unlike platform user groups, custom groups can be enriched with additional metadata like team lead, region, or other organizational information. Custom groups support hierarchical relationships through parent-child connections and serve as a source of truth for organizational structure within IDP. + +Custom User Groups can: +* Have members (users) +* Be organized in hierarchies with parent-child relationships +* Own components, systems, and other entities +* Be enriched with metadata for better context + +For more details on Custom User Groups, please refer to the [detailed docs](/docs/internal-developer-portal/catalog/user-group) here. + +Roles and resource groups can be assigned directly to users or inherited from user groups. Here's how you can [add users](https://developer.harness.io/docs/platform/role-based-access-control/add-users/) in Harness IDP. You can [add users manually](https://developer.harness.io/docs/platform/role-based-access-control/add-users/#add-users-manually) or through [automated provisioning](https://developer.harness.io/docs/platform/role-based-access-control/add-users/#use-automated-provisioning). User groups can be created at all scopes. @@ -131,6 +150,8 @@ With IDP 2.0, you can create resources at any scope: **Account**, **Org**, or ** | **Scorecards** | ✅ | ❌ | ❌ | Only supported at the Account scope currently. Org/Project scope support is planned in the future roadmap. | | **Layouts** | ✅ | ❌ | ❌ | Supported only at the Account scope currently. Org/Project scope support is planned. | | **Plugins** | ✅ | ❌ | ❌ | Plugins can be created and configured only at the Account scope. | +| **Custom User Groups** | ✅ | ❌ | ❌ | Custom User Groups can be created and managed only at the Account scope. | + ## Relations [IDP 2.0] diff --git a/docs/internal-developer-portal/catalog/migrate-catalog-scripts/catalog-scripts.md b/docs/internal-developer-portal/catalog/migrate-catalog-scripts/catalog-scripts.md index 216f89a9568..818ec66f1f8 100644 --- a/docs/internal-developer-portal/catalog/migrate-catalog-scripts/catalog-scripts.md +++ b/docs/internal-developer-portal/catalog/migrate-catalog-scripts/catalog-scripts.md @@ -33,6 +33,7 @@ import DynamicMarkdownSelector from '@site/src/components/DynamicMarkdownSelecto path: "/internal-developer-portal/catalog/migrate-catalog-scripts/content/populate-catalog/github-idp-1.md" } }} - defaultValue="IDP 2.0" + defaultSelection="IDP 2.0" + disableSort={true} toc={toc} /> \ No newline at end of file diff --git a/docs/internal-developer-portal/catalog/static/additionalinfocard.png b/docs/internal-developer-portal/catalog/static/additionalinfocard.png new file mode 100644 index 00000000000..805525b6378 Binary files /dev/null and b/docs/internal-developer-portal/catalog/static/additionalinfocard.png differ diff --git a/docs/internal-developer-portal/catalog/static/child-parent.png b/docs/internal-developer-portal/catalog/static/child-parent.png new file mode 100644 index 00000000000..7d9fd215a77 Binary files /dev/null and b/docs/internal-developer-portal/catalog/static/child-parent.png differ diff --git a/docs/internal-developer-portal/catalog/static/create-usergroup.png b/docs/internal-developer-portal/catalog/static/create-usergroup.png new file mode 100644 index 00000000000..c5e6467c0c0 Binary files /dev/null and b/docs/internal-developer-portal/catalog/static/create-usergroup.png differ diff --git a/docs/internal-developer-portal/catalog/static/duplicate.gif b/docs/internal-developer-portal/catalog/static/duplicate.gif new file mode 100644 index 00000000000..fb55ad68ef9 Binary files /dev/null and b/docs/internal-developer-portal/catalog/static/duplicate.gif differ diff --git a/docs/internal-developer-portal/catalog/static/layout-usergroup.png b/docs/internal-developer-portal/catalog/static/layout-usergroup.png new file mode 100644 index 00000000000..8d955b2bac4 Binary files /dev/null and b/docs/internal-developer-portal/catalog/static/layout-usergroup.png differ diff --git a/docs/internal-developer-portal/catalog/static/overview.png b/docs/internal-developer-portal/catalog/static/overview.png new file mode 100644 index 00000000000..ee8995159b1 Binary files /dev/null and b/docs/internal-developer-portal/catalog/static/overview.png differ diff --git a/docs/internal-developer-portal/catalog/static/user-group-overview.png b/docs/internal-developer-portal/catalog/static/user-group-overview.png new file mode 100644 index 00000000000..d259ea1b47c Binary files /dev/null and b/docs/internal-developer-portal/catalog/static/user-group-overview.png differ diff --git a/docs/internal-developer-portal/catalog/user-group.md b/docs/internal-developer-portal/catalog/user-group.md new file mode 100644 index 00000000000..7525ce187b9 --- /dev/null +++ b/docs/internal-developer-portal/catalog/user-group.md @@ -0,0 +1,36 @@ +--- +title: User Groups in Catalog +description: Learn how to define, manage, and use User Groups in Harness Internal Developer Portal to group related Components, APIs, and Resources. +sidebar_label: User Groups in Catalog +sidebar_position: 6 +keywords: + - Harness Internal Developer Portal + - Custom User Group + - User Groups + - Catalog + - IDP + - Team Organization + - Group Hierarchy +redirects: + - /internal-developer-portal/catalog/add-user-groups-in-catalog#idp1.0 + - /internal-developer-portal/catalog/user-group-entity#idp2.0 + - /internal-developer-portal/catalog/user-group + - /internal-developer-portal/catalog/user-group#idp1.0 + - /internal-developer-portal/catalog/add-user-groups-in-catalog +--- + +import DynamicMarkdownSelector from '@site/src/components/DynamicMarkdownSelector/DynamicMarkdownSelector'; + + diff --git a/docs/internal-developer-portal/idp-2o-overview/2-0-overview-and-upgrade-path.md b/docs/internal-developer-portal/idp-2o-overview/2-0-overview-and-upgrade-path.md index e2575b66d70..51d64bea55d 100644 --- a/docs/internal-developer-portal/idp-2o-overview/2-0-overview-and-upgrade-path.md +++ b/docs/internal-developer-portal/idp-2o-overview/2-0-overview-and-upgrade-path.md @@ -17,8 +17,8 @@ IDP 2.0 is an ongoing project under active iteration. Here is the most recent st | [**RBAC and Project/Org Hierarchy**](/docs/internal-developer-portal/rbac/scopes) | ✅ (Ready to onboard) | | [**Git Experience (YAML files in Git)**](/docs/internal-developer-portal/git-experience/gitx-journey) | ✅ (Ready to onboard) | | [**New System Entity for grouping**](/docs/internal-developer-portal/catalog/system-entity) | ✅ (Ready to onboard) | +| [**Custom User Groups**](/docs/internal-developer-portal/catalog/user-group) | ✅ (Ready to onboard) | | **Project/Org filters in Scorecards** | ⏳ ETA Oct 2025 | -| **Custom User Groups** | ⏳ ETA Oct 2025 | ::: @@ -333,11 +333,17 @@ The "Create Catalog" and "Register Catalog" steps previously used in IDP pipelin You can now directly use Harness IDP Catalog APIs to register new entities using YAML definitions without Git operations. A dedicated step for this functionality will be available soon. -### Custom User Groups and Custom Metadata +### Custom User Groups -In IDP 1.0, it was possible to create custom User Groups directly in the IDP Catalog without creating them as Harness User Groups. However, currently in IDP 2.0, this feature is not available - which means the only way to create User Groups is by creating them directly as Harness User Groups at the account level. +Harness IDP 2.0 supports Custom User Groups as first-class catalog entities! These groups differ from platform user groups synced from identity providers and offer several advantages: -However, we are currently working on introducing the concept of creating custom user groups, creating nested groups under groups and ingesting custom metadata on them as well. +* Create organizational groups directly in the IDP interface or via YAML definitions +* Model parent-child hierarchical relationships between teams and departments +* Enrich groups with metadata like team lead, region, and contact information +* Assign ownership of components, systems, and other catalog entities to custom groups +* Make IDP your source of truth for team modeling and organizational structure + +Custom User Groups are created at the account level and coexist with platform user groups. [Learn more about Custom User Groups](/docs/internal-developer-portal/catalog/user-group). ## Feature Compatibility Matrix (1.0 vs 2.0) @@ -388,7 +394,7 @@ However, we are currently working on introducing the concept of creating custom | Entity CRUD APIs | ❌ | ✅ | Entities can be created, updated, and deleted using Harness APIs. | | Catalog Ingestion APIs | ✅ | ✅ | | | Terraform Provider | ❌ | Planned | | -| Custom User Groups | ✅ | Planned | | +| Custom User Groups | ✅ | ✅ | | ## Timeline diff --git a/release-notes/internal-developer-portal.md b/release-notes/internal-developer-portal.md index 8a4c02f14f0..f48b744d2c4 100644 --- a/release-notes/internal-developer-portal.md +++ b/release-notes/internal-developer-portal.md @@ -24,7 +24,26 @@ Review the notes below for details about recent changes to Harness Internal Deve | **Version** | **prod0** | **prod1** | **prod2** | **prod3** | **prod4** | **prodeu1** | | ----------- | --------- | --------- | --------- | --------- | --------- | ----------- | -| [2025.08.v1](/release-notes/internal-developer-portal#august---202508v1) | ✅ | ✅ | ✅ | ⏳| ⏳ | ⏳ | +| [2025.09.v1](/release-notes/internal-developer-portal#september---202509v1) | ✅ | ✅ | ✅ | ⏳| ⏳ | ⏳ | +| [2025.08.v1](/release-notes/internal-developer-portal#august---202508v1) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | + +## September - [2025.09.v1] + +### [New Feature] Custom User Groups Entity + +Take control of your organizational structure with IDP 2.0's powerful new Custom User Groups! This game-changing feature transforms how teams are represented in your developer portal, bringing your real-world organizational structure into IDP as first-class catalog entities. + +![](./static/internal-developer-portal/user-group-overview.png) + +**What's in it for you:** + +* **True organizational modeling** - Create and manage custom team structures directly in IDP without depending on your identity provider +* **Powerful ownership attribution** - Make ownership crystal clear across your entire catalog with direct group assignments +* **Rich contextual metadata** - Add team leads, regions, and critical contact information to each group +* **Intuitive hierarchical relationships** - Build parent-child connections between teams and departments with automatic bi-directional linking +* **Complete UI and YAML support** - Create groups through the intuitive UI or via standard YAML definitions + +[Learn more about Custom User Groups](/docs/internal-developer-portal/catalog/user-group#idp2.0) ## August - [2025.08.v1] diff --git a/release-notes/static/internal-developer-portal/user-group-overview.png b/release-notes/static/internal-developer-portal/user-group-overview.png new file mode 100644 index 00000000000..d259ea1b47c Binary files /dev/null and b/release-notes/static/internal-developer-portal/user-group-overview.png differ diff --git a/src/components/DynamicMarkdownSelector/DynamicMarkdownSelector.tsx b/src/components/DynamicMarkdownSelector/DynamicMarkdownSelector.tsx index 86fc0390368..d5df11ae388 100644 --- a/src/components/DynamicMarkdownSelector/DynamicMarkdownSelector.tsx +++ b/src/components/DynamicMarkdownSelector/DynamicMarkdownSelector.tsx @@ -42,6 +42,8 @@ export interface DynamicMarkdownSelectorProps { toc: TOCItem[]; precedingHeadingID: string; nextHeadingID: string; + defaultSelection?: string; + disableSort?: boolean; } // Determine column count for visual balance @@ -57,8 +59,10 @@ const DynamicMarkdownSelector: React.FC = ({ toc, precedingHeadingID = "", nextHeadingID = "", + defaultSelection, + disableSort = false, }) => { - const labels = Object.keys(options).sort((a, b) => a.localeCompare(b)); + const labels = disableSort ? Object.keys(options) : Object.keys(options).sort((a, b) => a.localeCompare(b)); const buildHash = (sel: string, sec?: string) => `#${encodeURIComponent(normalize(sel))}${