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.

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

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🚧 (Work in Progress) ETA: Week of July 4, 2025

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.

Supported Git Providers in Harness IDP Git Experience​

Harness IDP Git Experience integrates with the following Git Providers:

  • GitHub (Cloud & Enterprise)
  • GitLab (Cloud & Self Hosted)
  • Bitbucket
  • Azure Repos
  • Harness Code

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.

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

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​

You can also switch branches from Git to view an alternate version of the entity's YAML. This action does not create a new entity; instead, it updates the existing one. 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.

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. Any changes made to the entity in IDP is committed back to Git.

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, allowing teams to apply review and approval workflows.
note

Note that we are actively working on adding bidirectional sync so that changes done in the YAML file also updates the entity in IDP using webhooks. This feature will land on or more July 4, 2025.

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.