Skip to main content

Git Experience for Harness IDP

For IDP 1.0 Customers

This Git Experience document is applicable only to IDP 2.0 customers, as the Harness IDP Git Experience is available exclusively in IDP 2.0. To learn how to upgrade, refer to the IDP 2.0 Upgrade Guide.

Supported Features in Git Experience​

FeatureStatus
Store entity YAML in Git✅ Available
Import YAML from Git and create a new entity✅ Available
IDP to Git changes: Make changes in IDP and commit changes to YAML file in Git✅ Available
Git to IDP changes: Make changes to YAML file in Git and update entity in IDP✅ Available

Harness Internal Developer Portal (IDP) integrates with the Platform Git Experience (GitX) to enable bi-directional Git-backed entity management. Harness Git Experience allows you to store and track your entity YAMLs in Git Repositories with bi-directional updates. This document outlines how developers and platform engineers interact with Git Experience throughout the entity lifecycle.

Note

With the IDP Git experience feature, one entity can have only one YAML file. Unlike IDP 1.0, storing multiple entities within a single YAML is no longer supported in IDP 2.0. This design choice is in line with the rest of the Harness platform, which emphasizes clarity and consistency through single-entity YAML definitions. To understand more about this and other key differences, see the breaking changes in IDP 2.0.

Supported IDP Entities in Git Experience​

IDP Catalog entity YAMLs (Component, API, Resource) and Workflow YAMLs can be stored in Git using Git Experience. However, configuration of other resources such as Scorecards, Plugin configurations, Layouts, etc. can only be done using the UI or API.

Note: For the full list of supported entities, refer to the Supported IDP Entities in Git Experience documentation.

Supported Git Providers in Harness IDP Git Experience​

Harness IDP Git Experience integrates with the following Git Providers:

Storing Entity YAMLs​

Harness Git Experience with IDP 2.0 allows you to store your Catalog entity YAMLs and Workflow YAMLs in the following two ways:

  1. Inline: Your entity YAML is stored in the Harness database, and the entity exists as an Inline Entity.
  2. Remote: Your entity YAML is pushed to Git, and the entity exists as an Remote Entity.

Read more about Harness Platform Git Experience Requirements. To learn more about Harness-native Catalog entity YAML, go to Catalog YAML.

Creating Inline Entities​

With Inline Entities, your entity's YAML is stored in the Harness database. You can edit and manage your entity's YAML from the Harness UI directly.

Inline Entity

Creating Remote Entities​

With Remote Entities, you can store your entity YAMLs in your Git repositories with bi-directional real-time sync support.

Let's get started, so when a user creates a new Catalog entity - they can choose to store the YAML inline or in a remote Git repository. This selection is available upfront in the entity creation form.

Once Git is selected, users can configure the repository details, connector, branch, and YAML file path. Changes made in the entity via the Harness UI are committed to the Git repo (either directly or through a pull request).

note

Changes made to the YAML file in Git are automatically reflected in the entity using webhook-triggered updates. To understand more about this feature, please refer to Updating and Syncing Entities with Git

Converting Inline to Remote Entity​

Users who initially created an entity as Inline (stored in the Harness database) can convert it to a Remote Entity (Git-backed) at any time using the Edit page in the Harness UI.

You can do this in two ways:

  • Manually via the UI: Navigate to the entity’s Edit screen, configure the Git settings (connector, repo, branch, and file path), and save the changes. This moves the entity YAML to Git and enables Git-based tracking.
  • In Bulk using a Script: For larger migrations, Harness provides a script that helps automate the conversion of multiple entities from Inline to Remote, storing their YAMLs in a Git repo following a structured format. To learn how to use this script and view complete steps, refer to the official migration guide - Store Entity YAMLs in Git

Managing Multiple Branches​

Harness Git Experience allows users to view the YAML definition of a Git-backed entity across any available branch. This is especially helpful for reviewing PR changes, testing variations, or managing configuration workflows in different environments.

You can use the branch selector from the entity view in the Software Catalog to toggle between branches and inspect the YAML for that branch.

This is especially useful in scenarios where direct commits to the main branch are restricted due to organizational policies, and changes need to go through a pull request workflow.

Branch Selection in GitX

While you can inspect and preview YAMLs across different branches, only the default branch (as configured during entity creation) is actively used by Harness IDP for rendering and syncing entity definitions.

note

Note that the final entity page view in IDP will still render the main/default branch.

Importing an Entity from Git (using YAML)​

In Harness IDP, users can also create new entities and Workflows by importing their YAML definitions stored in Git repositories directly into Harness IDP. This feature allows teams to reuse pre-defined configurations, onboard services faster, and migrate from automation workflows or existing repositories.

Pre-requisites​

  • Enable API Access: For connection types and authentication methods where API access is not already enabled by default, you'll have to enable it from the Git connector settings. API Access is required for using Harness Git Experience. Refer to these docs to enable API access.

Import an Entity YAML​

You can create a new entity or workflow in Harness IDP directly from your Git YAML by using this Import flow. Please refer to the following steps to import any entity from Git.

Harness native YAML vs Backstage YAML​

To use this feature, Backstage YAML is not supported directly. Since IDP 2.0 uses a new data model, existing YAMLs from IDP 1.0 (Backstage-native) must be converted using Harness CLI, UI editors, or migration scripts. To understand more about converting IDP 1.0 YAMLs to IDP 2.0 YAMLs, please refer to Converting IDP 1.0 YAMLs

Entity Scope and Connector Rules​

Some important constraints exist during the import process:

  • Entity Scope is Fixed: The scope (Account, Org, or Project) of the entity is determined by the scope you select initially. Make sure your imported YAML includes the appropriate scope identifiers i.e. projectIdentifier and orgIdentifier; otherwise, it will result in an error.
  • Harness Code & Other Git Providers:
    • Harness Code Repository: When importing via Harness Code, YAMLs can be sourced from any repository that the user has access to. The repo’s scope does not affect the entity scope. The following details are required in importing an entity from Git using Harness Code Repository:
      • Repository: Git Repository where your Entity YAML is stored.
      • Git Branch: Branch of your Repository where your Entity YAML is stored.
      • YAML Path: Path of your YAML File.
    • Third-Party Git Providers: When using other Git providers (GitHub, GitLab, Bitbucket, Azure Repos), the same rules apply — the scope selection and YAML determines the entity's scope. The following details are required in importing an entity from Git using Third-party Git Providers:
      • Git Connector: Git Connector added in your Harness IDP
      • Repository: Git Repository where your Entity YAML is stored.
      • Git Branch: Branch of your Repository where your Entity YAML is stored.
      • YAML Path: Path of your YAML File.

Updating and Syncing Entities with Git​

Once an entity in Harness IDP is backed by Git Experience, it becomes tightly coupled with its corresponding YAML definition in the Git repository. This enables a seamless two-way sync between Harness and Git, ensuring that the Git repository always reflects the source of truth - whether the changes originate from the UI or from Git directly.

When a user edits the entity using the Harness UI (such as updating metadata, annotations, or layout), GitX pushes the changes back to Git. This can happen via:

  • A direct push, where the update is committed directly to the configured branch, or
  • A pull request made when we change the branch, allowing teams to apply review and approval workflows.

Bi-directional Sync between Harness and Git​

Git Experience enables bi-directional entity updates, meaning:

Changes in Git reflect in the Harness entity YAML​

When a user updates the YAML file directly in the Git repository (for example, through a commit or pull request), GitX listens to webhook events configured for the repository. Once triggered, the webhook causes Harness to automatically reload the YAML and apply those changes to the corresponding entity.

Changes in Harness entity YAML reflect in Git​

Webhook Auto-Creation​

When Git Experience (GitX) is configured in Harness, a webhook is automatically created in your Git repository. This webhook allows IDP GitX to listen for changes and automatically trigger YAML reloads. If the webhook is configured and any updates are pushed to the repository, Harness also validates the updated IDP catalog YAMLs to ensure correctness and consistency.

Webhook Auto-Creation

Experience Bi-directional Sync (via Webhooks)​

Entity Sync Status & Version Drift​

To provide complete visibility into the sync state of an entity, GitX shows real-time metadata on the entity’s View/Edit pages. This includes:

  • Sync status: Indicates whether the entity is currently in sync with the YAML file in Git.
  • Out-of-sync warnings: If the entity’s version in Harness diverges from its YAML file in Git (e.g., webhook failed or someone made conflicting changes), Harness will flag this status and notify the user.
  • Connector, branch, file path: These GitX properties are always visible so users can troubleshoot and validate the entity’s configuration.