> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/use-idp/software-catalog/create-entity/catalog-discovery/integrations/github.md).

# GitHub Integration

Auto-discover GitHub repositories, teams, and AI assets across one or more GitHub organizations and populate the IDP Catalog for service discovery and dependency mapping.

The GitHub integration automatically discovers repositories, teams, and AI assets from one or more GitHub organizations and brings them into the IDP Catalog. A single integration can sync multiple organizations when its connector uses a Classic Personal Access Token (PAT). On the other hand, you can sync only one organization if your connector uses a GitHub App or a fine-grained token.

Once discovered, entities can be registered as new catalog entries or merged into existing ones, enriching them with GitHub-sourced metadata for service discovery, team ownership, and dependency mapping.

***

## Supported GitHub types <a href="#supported-github-types" id="supported-github-types"></a>

The integration supports the following GitHub deployments:

| GitHub type                                  | Supported | Notes                                                                                      |
| -------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
| GitHub (public)                              | Yes       | Original support.                                                                          |
| GitHub Enterprise Cloud (SaaS)               | Yes       | Same as public, hosted by GitHub.                                                          |
| GitHub Enterprise Server (GHES, self-hosted) | Yes       | Requires the connector URL to point at the GHES instance and include the org path segment. |

{% hint style="warning" %}
**ENTERPRISE SAAS IS NOT THE SAME AS ENTERPRISE SERVER**

GitHub Enterprise Cloud (SaaS) is hosted by GitHub and behaves like public GitHub. GitHub Enterprise Server (GHES) is self-hosted on your own infrastructure and requires the connector URL, delegate network access, and token to point at your GHES instance. Do not conflate the two.
{% endhint %}

For each entity type, the integration collects the following:

| Entity         | What it provides                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Repository** | Repository URL, primary language, language breakdown, latest release details, full release history, and whether an agents file is present. |
| **Team**       | Team membership and ownership data.                                                                                                        |
| **AI Assets**  | AI/ML asset metadata discovered from manifest files in repositories.                                                                       |

***

## Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

{% hint style="warning" %}
**Requires Delegate Version Upgrade**

Your [Harness Delegate](/harness-ai/use-harness-platform/delegates/delegate.md) image version must be [26.09.90004](https://developer.harness.io/release-notes/delegate#version-260990004) or above. Upgrade it if you have an older version.
{% endhint %}

The following are needed to get the integration running:

* Ensure the feature flag **`IDP_INTEGRATIONS`** is enabled. Contact [Harness Support](https://www.harness.io/support) to enable it.
* You have the required RBAC permissions to manage integrations. All integration operations require the **`IDP_INTEGRATION_EDIT`** permission on the **`IDP_INTEGRATION`** resource type.
* A [GitHub PAT Connector](https://www.youtube.com/watch?v=7RZXGWdUv9o) or [GitHub App Connector](/harness-ai/use-harness-platform/connectors/code-repositories/git-hub-app-support.md) is configured in Harness with the credentials needed to access your GitHub organizations. Ensure that the connector has the [necessary permissions on your GitHub](#github-permissions). You can create a new connector directly during the integration setup.
* To sync multiple GitHub organizations from a single integration, the connector must use a **Classic Personal Access Token (PAT)**. GitHub limits fine-grained PATs and GitHub Apps to one organization, so connectors that use them can sync only one organization per integration. If any organization you plan to sync enforces SAML SSO, ensure your classic PAT is authorized for that organization. Go to [Classic Personal Access Token](#classic-personal-access-token) for the steps.
* The connector's **URL Type** should be set to **Account**, and the **GitHub Account URL** should match your GitHub type (public/enterprise-cloud/enterprise-server) as described in [Configure setup & connectivity](#id-2-configure-setup-and-connectivity).
* Make sure to turn on `Enable API access` in the connector, and use the same PAT in **Authentication** and **API Authentication** sections as shown below:

  ![Enable API Access and use same Personal Access Token](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-f48e23b6fa9d02c48f0a979f835704e5c29f706f%2Fcommon-pat.png?alt=media)

### GitHub Enterprise Server (GHES) prerequisites <a href="#github-enterprise-server-ghes-prerequisites" id="github-enterprise-server-ghes-prerequisites"></a>

If you connect to a self-hosted GHES instance, ensure delegate connectivity before you begin:

* **Delegate network access:** The delegate selected by the connector must reach the GHES host. Test reachability with `curl -I https://<ghes-host>`. If GHES is IP-allowlisted, allowlist the delegate egress IP. Delegates are not allowlisted for customer GHES instances by default.

{% hint style="info" %}
**PROXY CONFIGURATION**

If your environment blocks outbound third-party traffic and routes it through a proxy, you will need to configure proxy settings on your Harness Delegate. Once configured there, the proxy settings are automatically picked up by IDP integrations. No additional setup is needed on the integration side.

Here is how to set it up: [Configure delegate proxy settings](/harness-ai/use-harness-platform/delegates/delegate/manage-delegates/proxy/configure-delegate-proxy-settings.md)
{% endhint %}

***

## Enable the GitHub integration <a href="#enable-the-github-integration" id="enable-the-github-integration"></a>

### 1. Navigate to the integrations page <a href="#id-1-navigate-to-the-integrations-page" id="id-1-navigate-to-the-integrations-page"></a>

1. In Harness, open the **Internal Developer Portal**.
2. From the left sidebar, click **Configure**.
3. In the left navigation menu, click **Integrations**.

   ![Figure 1: Navigation Path of GitHub Integration](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-b1c3459c795c5b31311994cfa55155905900e2a5%2Fgh-integration-nav.png?alt=media)
4. On the Integrations page, click **+ New Integration** at the top.
5. Select **GitHub** from the integration type picker. You will be taken to the **Auto Discover GitHub Integration** page.

### 2. Configure setup & connectivity <a href="#id-2-configure-setup-and-connectivity" id="id-2-configure-setup-and-connectivity"></a>

This section connects Harness IDP to GitHub and defines which GitHub organizations the integration syncs.

![Figure 2: Setup & Connectivity](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-7e6841d63517060cfa37894597e2f3b9af500338%2Fgh-setup-connectivity.png?alt=media)

1. Enter a name in the **Integration Name** field. This name appears on the integration card on the **Integrations** page (e.g., `GitHub Production`).
2. Click the **Choose GitHub connector** dropdown and select the GitHub connector you want to use to pull data into the IDP. The connector's credential determines which organizations you can select in the next step.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>DO NOT HAVE A GITHUB CONNECTOR YET?</strong></p><p>If no connectors appear in the dropdown, you need to first create a GitHub connector in Harness. Once saved, it will appear in the dropdown here. The following video shows how to create a GitHub connector that uses a classic personal access token and how to authorize the token for SSO-enabled organizations.</p><div data-gb-custom-block data-tag="embed"><iframe src="https://youtu.be/7RZXGWdUv9o"></iframe></div></div>

   Set the GitHub connector URL based on your GitHub type:

   | Scenario                                 | Correct URL format                                                            | Do not use                                   |
   | ---------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------- |
   | Public GitHub or GitHub Enterprise Cloud | `https://github.com/<org>` or `https://github.com/<username>`                 | -                                            |
   | GHES, org scope                          | `https://<ghes-host>/<org>` (for example, `https://github.acme.com/acme-org`) | `https://<ghes-host>` alone (fails silently) |
   | GHES, account scope                      | Not currently supported, org is required                                      | -                                            |

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p><strong>THE ORG PATH SEGMENT IS MANDATORY FOR GHES</strong></p><p>Setting the connector URL to only the GHES host (for example, <code>https://github.acme.com</code>) causes the sync to fail with no records ingested. Always include the org path segment: <code>https://&#x3C;ghes-host>/&#x3C;org></code>.</p></div>
3. Under **GitHub Organizations**, click **Configure**. No organizations are selected by default, and you must select at least one organization to continue.
4. In the **Configure Organizations** panel, select the organizations you want this integration to sync. The panel lists the organizations that the connector's credential can access.

   * Use the search field to find an organization by name. The search covers the current page only.
   * Select **Select all on this page** to select every organization on the current page.
   * Use **Prev** and **Next** to move between pages when the list spans multiple pages.

   ![Figure 3: Configure Organizations panel with two organizations selected](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-82343a1f8af30caba852e2d98654657994930f5a%2Fgh-configure-organizations.png?alt=media)

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p><strong>CONNECTOR REQUIRES ORG-LEVEL PERMISSIONS</strong></p><p>The integration runs org-level queries to discover repositories and teams in each selected organization. Ensure the connector's credential has org-level permissions on every organization you select, and is <a href="#classic-personal-access-token">SSO-authorized</a> for organizations that enforce SAML SSO.</p></div>
5. Click **Update**. The **GitHub Organizations** field shows the number of selected organizations and their names, and the **Mapping & Correlation** section becomes available.

{% hint style="info" %}
**ORGANIZATION SELECTION**

* **Credential type:** Only connectors that use a classic PAT can sync multiple organizations. Go to [GitHub permissions](#github-permissions) for details.
* **Personal repositories:** The integration discovers repositories that belong to the selected organizations. Repositories owned by a personal user account are not discovered.
* **Sync time:** Each selected organization adds to the sync time and GitHub API usage of every sync cycle. The time it takes depends on the sync frequency and the size of the orgs (no. of repos, issues, PRs and other kinds). Integrations with many organizations may take proportionally longer to sync.
  {% endhint %}

### 3. Configure mapping & correlation <a href="#id-3-configure-mapping-and-correlation" id="id-3-configure-mapping-and-correlation"></a>

This section defines how GitHub entities are mapped to IDP catalog entities and how they are correlated with existing records.

The integration supports three entity types: **Repository Entity**, **Team Entity**, and **AI Assets Entity**, each with its own toggle, registration behavior, and field configuration.

![Figure 4: Available Entities - Repository, Team, and AI Assets](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-0506d56992cd7590fa992d920aa1ff85c075db10%2Fgh-entities.png?alt=media)

**Repository entity**

The Repository Entity mapping imports GitHub repositories as catalog entities, with configurable `Kind` or `Type`.

{% hint style="info" %}
**MONOREPO NOT SUPPORTED**

The GitHub integration registers each repository as a single service across all GitHub types. Monorepos, where one repository contains multiple services, are not currently supported, so the individual services within a monorepo cannot be registered as separate catalog entities.
{% endhint %}

![Figure 5: Enable Repository Entity](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-bfb5b303e66e017f961ae924ae2113261501f522%2Frepo-entity.png?alt=media)

1. Ensure the **Repository Entity** toggle is turned on.
2. Under **Entity Registration Behavior**, choose how repositories are brought into the catalog:
   * **Register & Merge** *(Default)* - Registers new entities and updates existing ones when a match is found. This is the recommended option for most setups.
   * **Register** - Creates new catalog entities from GitHub. Does not merge with existing entities.
   * **Merge** - Links discovered repositories to existing catalog entities. Matching entities are recommended automatically, but you can choose a different one.
3. Choose the **Kind** and **Type** from the dropdown. By default, it is `Component` and `service` respectively. Configurability varies by registration behavior:

   | Registration Behavior | Kind         | Type             |
   | --------------------- | ------------ | ---------------- |
   | `Register & Merge`    | Configurable | Configurable     |
   | `Register`            | Configurable | Configurable     |
   | `Merge`               | Configurable | Not configurable |
4. Under **Correlation Mapping**, set the **Ingested Data Path** (from GitHub) and the corresponding **Catalog YAML Path** (from your IDP entity) to define how records are matched. The operator supports `Equals` and `Contains`.
5. Optionally, click **Configure** next to **Configure fields (optional)** to customize which GitHub fields are synced to the catalog. By default, all available fields are selected.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>RELEASE DATA LIMIT</strong></p><p>GitHub repository entities include release metadata for the latest 10 releases only (if they exist). Older releases are not ingested into the catalog.</p></div>
6. Optionally, click **Configure** next to **Configure Secondary Kinds (optional)** to control which additional data streams are synced for each repository. By default, pull requests and issues are not selected.

   Secondary kinds enrich each repository entity with development activity data. By surfacing pull requests and issues, IDP gives teams an instant view of how actively an entity is being developed, how stable it is, and whether it is progressing or at risk, all without leaving the platform.

   ![Figure 6: Configure Secondary Kinds panel](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-d1d3648e08115ebbb8c301ac22f2aaa86b491c54%2Fgh-secondary-kinds.png?alt=media)

   The following secondary kinds are available:

   | Secondary Kind    | Description                                                                                                                                                                                                                                                                                                                                                      |
   | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Issues**        | Open and closed issues for each repository.                                                                                                                                                                                                                                                                                                                      |
   | **Pull Requests** | Pull request details for each repository. The first sync ingests pull requests from the last 30 days; subsequent syncs backfill all new pull requests incrementally. If not selected, the pull request list on the [Source Code tab](/internal-developer-portal/use-idp/software-catalog/create-entity/entity-details.md#source-code-tab) will not be populated. |

   On the first sync, IDP fetches a limited snapshot per repository. If the total PRs across all repositories exceed the per-sync limit (i.e. 5000), the excess is not dropped. Subsequent syncs backfill the remaining PRs and pick up any new ones.

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p><strong>SECONDARY KINDS CANNOT BE CHANGED AFTER SETUP</strong></p><p>These selections are locked once the integration is created and they cannot be modified later. This is because it would need fetching, remembering, and displaying past data (a.k.a. backfilling) which is currently not supported. Choose carefully before confirming.</p></div>

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>WHERE DOES THIS DATA APPEAR?</strong></p><p>Secondary kinds data is surfaced on the <a href="/internal-developer-portal/use-idp/software-catalog/create-entity/entity-details.md">Entity Details</a> page for each repository. It does not appear in the <strong>Ingested Properties</strong> YAML in the Entity Inspector.</p></div>

**Team entity**

The Team Entity mapping imports GitHub teams as catalog entities, with configurable `Kind` or `Type`.

![Figure 7: Enable Team Entity](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-d2e8d957fb780ff1803829e07186f89ca69da498%2Fgh-team-entity.png?alt=media)

1. Ensure the **Team Entity** toggle is turned on.
2. Under **Entity Registration Behavior**, choose the registration behavior as described above for [Repository Entity](#repository-entity).
3. Choose the **Kind** and **Type** from the dropdown. By default, it is `User Groups` and `Team` respectively. Configurability varies by registration behavior:

   | Registration Behavior | Kind         | Type             |
   | --------------------- | ------------ | ---------------- |
   | `Register & Merge`    | Configurable | Configurable     |
   | `Register`            | Configurable | Configurable     |
   | `Merge`               | Configurable | Not configurable |
4. Configure the **Correlation Mapping** fields as needed.
5. Optionally, click **Configure** next to **Configure fields (optional)** to customize the field mapping.

{% hint style="info" %}
**REPOSITORY VISIBILITY FOR TEAMS**

The catalog only surfaces repositories for which the GitHub team has Admin permission. Repositories with lower-level access will not show up in the [Ingested Properties](#ingested-properties).
{% endhint %}

**AI assets entity**

The AI Assets Entity mapping discovers and imports AI/ML assets found in your GitHub repositories through manifest-level, API-based scanning. No repository cloning is required.

![Figure 8: Enable AI Assets Entity](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-08bc2f8f672184e7b5d4c2d8f5225a5f528cf529%2Fai-assets-entity.png?alt=media)

You can discover the following class of asset:

* **`ai_asset`** - Claude Code ecosystem components defined in `.claude-plugin/` manifests or standalone `.claude/` directories. Includes the following types:

  | Type      | Description                      | Example                                    |
  | --------- | -------------------------------- | ------------------------------------------ |
  | `plugin`  | A Claude Code plugin bundle      | `make-agent-friendly`, `harness-hql`       |
  | `skill`   | A user-invocable task definition | `python-conventions`, `hql`, `dbops`       |
  | `agent`   | An autonomous agent definition   | `python-explorer`, `doc-generator`         |
  | `command` | A CLI-style command              | `run`, `suggest-workflows`, `add-fme-step` |

{% hint style="info" %}
**MONOREPO SUPPORT**

The current implementation scans for plugin manifests and `.claude/` directories at the repository root only. Subdirectory scanning of AI assets in a monorepo might be planned in a future release.
{% endhint %}

{% hint style="info" %}
**FIND YOUR IMPORTED ENTITIES IN THE CATALOG**

This asset class is registered in the IDP Catalog under `AIAsset` kind with its respective types, and is browsable under the **AI Assets** tab in the [Catalog](/internal-developer-portal/use-idp/software-catalog/overview.md)
{% endhint %}

{% hint style="info" %}
Harness IDP includes out-of-the-box scorecard checks for AIAsset entities discovered through this integration. See [Catalog Info YAML data source](/internal-developer-portal/use-idp/scorecards/create-scorecards/data-sources.md#catalog-info-yaml).
{% endhint %}

**View AI asset instructions**

When AI assets of type `skill` or `agent` are imported, IDP automatically fetches their corresponding instruction file (for example, `SKILL.md`) from GitHub and stores it along with the entity. This powers the **Instructions** tab on the entity page as shown below.

![Figure 9: AI Assets Instructions](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-8c57fac04e5e5e1bb3d8f96072381d0a040e1004%2Finstructions.gif?alt=media)

Additional metadata is also captured as annotations on the entity, including commit count, last commit message, author, and source location. These are visible in the **Entity Inspector** under **Metadata**.

However, this requires you to add an `InstructionsTab` component to your AI Asset layout:

1. Go to **Configure** → **Layout** in the IDP sidebar.
2. In **Catalog Entities**, click **AI Asset**.
3. Click **Edit Layout**.
4. Add the following definition (within `tabs` object) to your layout YAML:

   ```yaml
   - path: /instructions
     title: Instructions
     contents:
       - component: InstructionsTab
   ```

   ![Figure 10: Edit Layout to display Instructions tab on Entity](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-4576248efbe80c75599d199452fe5023d1f2b1b8%2Flayout-edit.gif?alt=media)
5. Click **Save**.

Once added, the **Instructions** tab appears on each AI asset entity page and renders the instruction file fetched from GitHub.

{% hint style="info" %}
The Instructions tab is currently supported for `skill` and `agent` type AI assets. Support for `command` type may be added in a future release.
{% endhint %}

### 4. Configure advanced settings <a href="#id-4-configure-advanced-settings" id="id-4-configure-advanced-settings"></a>

The **Advanced Settings** section controls how frequently IDP syncs with GitHub and how far back historical data is pulled.

![Figure 11: Advanced Settings](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-7f8306970bc78dd8cab8e069dac77b86c3f9d23e%2Fgh-advanced-settings.png?alt=media)

1. Select an **Update Frequency** from the dropdown to control how often IDP polls GitHub for new data.

   Available options: `30 min`, `1 hour`, `3 hours`, `6 hours`, `12 hours`, `1 day`.
2. Set the **Select start date** to define the earliest date from which IDP will pull GitHub data. Any data before this date will be excluded. By default, this is set to one year prior to today.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>START DATE UPDATE LIMITS</strong></p><p>The start date may be updated after the integration is configured, but only to an earlier date (up to 1 year old) than the one originally selected. It cannot be moved forward.</p></div>
3. Once all sections are configured, click **Confirm & Enable**. A confirmation dialog will appear before the changes are applied.

The integration is now enabled and IDP begins syncing data from each selected GitHub organization. Discovered repositories, teams, and AI assets appear in the [**Discovered** tab](#discovered-tab).

***

## Discover and import GitHub entities <a href="#discover-and-import-github-entities" id="discover-and-import-github-entities"></a>

This section covers how to view the GitHub entities discovered by the integration and import them into your IDP Catalog.

### Discovered tab <a href="#discovered-tab" id="discovered-tab"></a>

After the integration runs, all GitHub entities detected across the selected organizations appear in the **Discovered** tab. Use the **Repository**, **Team**, and **AI Assets** sub-tabs to switch between entity types. If entities do not appear, use the **Sync** button at the top right to manually refresh.

Each entity shows the organization it belongs to below its name (for example, `Org: acme-platform`). To view entities from specific organizations only, open the **Org** dropdown and select one or more organizations. Use the search field in the dropdown to find an organization, and click **Clear Selection** to view entities from all selected organizations again.

![Figure 12: 'Discovered' tab showing GitHub Repositories, Teams, and AI Assets](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-69c555564ff1187d1dc18d76f5d460e7f98eac52%2Fdiscovered-tab-gh.png?alt=media)

For each discovered entity, you can see its name, the recommended catalog action, kind, and the date it was detected. You can choose how to bring entities into the catalog using one of the following actions:

* **Register** *(typically used when no matching catalog entity exists)* - Creates a new catalog entity populated with the GitHub metadata. `Type` is editable by the user.
* **Merge** *(shown as Recommended when a matching catalog entity is found)* - Links the discovered entity to an existing catalog entity, enriching it with GitHub data. The suggested matching entity is shown automatically and can be changed.

{% hint style="info" %}
**BULK IMPORT AND AUTO IMPORT OPTIONS**

* **Bulk Import** - Select entities individually using the checkboxes, or use the floating window at the bottom of the page to bulk-select by action type. Open the **Select entities** dropdown to choose **All services**, **Register**, or **Merge (Recommended)**, then click **Import selected entities**.
* **Auto Import** - Toggle **Auto-import future discovered entities** in the top right of the Discovered tab to automatically import all future entities without manual review. You can change this preference at any time.
  {% endhint %}

### Imported tab <a href="#imported-tab" id="imported-tab"></a>

The **Imported** tab displays all GitHub entities that have been brought into the catalog. Use the **Repository**, **Team**, and **AI Assets** sub-tabs to view each entity type separately.

![Figure 13: 'Imported' tab showing GitHub entities linked to catalog entities](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-aaf6b162bfea9ea8a8648079f95e32d8fed0e397%2Fimported-tab-gh.png?alt=media)

It displays the following data:

| Column            | Description                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| **GitHub Entity** | The name of the entity from GitHub, along with its import status (for example, **Merged** or **Registered**). |
| **Entity**        | The linked IDP catalog entity and its ID.                                                                     |
| **Kind**          | The catalog entity kind (e.g., `component` for repositories, `group` for teams, `aiasset` for AI assets).     |
| **Type**          | The catalog entity type (e.g., `service` for repositories, `team` for teams).                                 |
| **Scope**         | The Harness account scope the entity belongs to.                                                              |
| **Imported At**   | The timestamp when the entity was imported.                                                                   |

{% hint style="warning" %}
**UNLINK AN IMPORTED ENTITY**

To stop syncing a specific entity without deleting the catalog entity, use the three-dot menu on any row and select **Unlink**. This stops sync updates while keeping the IDP entity and its existing data intact.
{% endhint %}

### Events tab <a href="#events-tab" id="events-tab"></a>

The **Events** tab logs all sync and lifecycle activity for this integration. Use it to verify that syncs are running, confirm that imports completed successfully, and investigate any failures.

For the full event type reference and detail panel fields, go to [Integration Events](/internal-developer-portal/use-idp/software-catalog/create-entity/catalog-discovery/integration-events.md).

![Figure 14: 'Events' tab showing all activity logs](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-82e11d5c80abfc1c48cd25e8003a3810482bc680%2Fevents-tab-gh.png?alt=media)

***

## View GitHub entities in the catalog <a href="#view-github-entities-in-the-catalog" id="view-github-entities-in-the-catalog"></a>

Once imported, GitHub entities are available in the **Catalog** section of IDP as standard catalog entities.

Each imported GitHub repository is registered with:

* **Kind:** `Component`
* **Type:** `service`
* **Scope:** The Harness account the integration belongs to

Each imported GitHub team is registered with:

* **Kind:** `Group`
* **Type:** `Team`
* **Scope:** The Harness account the integration belongs to

Each imported AI asset is registered with:

* **Kind:** `aiasset`
* **Scope:** The Harness account the integration belongs to

Open any entity to view GitHub-sourced data directly on the entity details page. This data is displayed through two dedicated UI components: a card on the **Overview** tab and a **Source Code** tab. Both require a one-time layout configuration, described in the [next section](#layout-for-github-components).

### Layout for GitHub components <a href="#layout-for-github-components" id="layout-for-github-components"></a>

To display GitHub data on the [entity details](/internal-developer-portal/use-idp/software-catalog/create-entity/entity-details.md) page, you need to add the two GitHub components to the relevant entity layout. This is a one-time configuration per entity kind and type.

1. From the left sidebar of IDP, go to **Configure** → **Layout** → **Catalog Entities**.
2. Edit the existing layout for your entity or create a new one.
3. Select the **Entity Kind** (e.g., `component`) and the **Entity Type** (e.g., `service`) that matches your imported GitHub entities.
4. In the YAML editor, add the `IntegrationsContent` component inside the **Overview** tab's `contents` block, and add a new **Source Code** tab using the `SourceControlTab` component.

   ![Figure 15: Entity Layout configuration for GitHub components](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-514b247a8048e8d285a5cfb89de8bc508787eeba%2Fgh-layout-config.png?alt=media)

   The relevant YAML additions are:

   ```yaml
           - component: IntegrationsContent
             specs:
               props:
                 variant: gridItem
               gridProps:
                 md: 12
   ```

   ```yaml
       - name: Source Code
         path: /source-code
         title: Source Code
         contents:
           - component: SourceControlTab
   ```
5. Click **Save** to apply the layout changes. The GitHub components will now appear on all entity detail pages of the selected kind and type that have GitHub data.

### Cards in overview tab <a href="#cards-in-overview-tab" id="cards-in-overview-tab"></a>

After the layout is configured, a `Source Control Management` card appears in the **Overview** tab of any entity that has GitHub data linked to it. The card displays the key GitHub metadata ingested for that entity, sourced from the entity's [ingested properties](#ingested-properties).

![Figure 16: GitHub Cards on the Overview tab](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-b839db9459949cd11c4338ed68f1ec5997721b0c%2Fgh-card-overview.gif?alt=media)

If the GitHub integration has not been configured for the entity, the card shows a **Not configured** state with a link to the Integrations page.

### Source code tab <a href="#source-code-tab" id="source-code-tab"></a>

The **Source Code** tab provides a more complete view of the GitHub data for the entity. This tab fetches the latest possible data using the integration ID and entity UUID.

![Figure 17: Source Code tab showing full resource details](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-6f6addeb263e273ecea3b998c22925fab20419cd%2Fsourcecode.png?alt=media)

{% hint style="info" %}
**FEATURE HIGHLIGHTS**

* The tab shows all available fields for the resource type, including fields not present in the **Overview**.
* All the fields are dynamic.
* The Open and Merged PR numbers and the Pull Requests table shows PRs updated since 30 days before integration setup, limited to the 1000 most recently updated PRs.
  {% endhint %}

### Ingested properties <a href="#ingested-properties" id="ingested-properties"></a>

To inspect the raw data ingested from GitHub, open the entity and click **View YAML** → **Ingested Properties** in the Entity Inspector.

![Figure 18: Entity Inspector Page showing Ingested Properties](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-7c7e7a8f747c69d0ddd62dfddd0cf7ad8c5aa0a7%2Fcatalog-yaml-gh.gif?alt=media)

Ingested properties are stored in two sections of the entity YAML:

* **`metadata.integration`** - Tracks which integrations are linked to this entity, including the entity action (e.g., `REGISTER` or `MERGE`) and the linked entity UUID for each integration instance.
* **`integration_properties.GitHub`** - Contains the GitHub-specific data for the entity, organized by entity type. For repository entities, this includes repository metadata such as name, URL, and associated teams. For team entities, this includes team membership and hierarchy data.

***

## Manage the GitHub integration <a href="#manage-the-github-integration" id="manage-the-github-integration"></a>

### Edit the integration <a href="#edit-the-integration" id="edit-the-integration"></a>

To update the integration name, the selected GitHub organizations, or the mapping and correlation settings, navigate to the **Integrations** page, find your GitHub integration card, and click **View**. From there, click **Configuration** to open the edit screen.

### Add or remove organizations <a href="#add-or-remove-organizations" id="add-or-remove-organizations"></a>

You can add or remove organizations on an existing integration at any time without recreating it. Organizations that stay selected continue syncing incrementally from their last sync.

1. Go to **Integrations** and open your GitHub integration using the **View** button.
2. Click **Configuration** at the top.
3. Under **GitHub Organizations**, click **Configure**.
4. In the **Configure Organizations** panel:

   * To remove an org, uncheck the selected organization(s) you no longer want to sync.
   * To add an org, click the **Refresh** button next to the searchbox. IDP refetches the list of organizations from GitHub. Next, you may select the org(s) you wish to sync.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Points to Remember</strong></p><ul><li>If the credential used in the connector gains access to another organization (for example, after you authorize the classic PAT for another SSO-enabled organization), use <strong>Refresh</strong>.</li><li>If the credential loses access to a selected organization, the other selected organizations continue to sync. This does not impact the already imported catalog entities from the old org.</li></ul></div>
5. Click **Update**.
6. Click **Confirm** to save the integration.

{% hint style="info" %}
**INTEGRATIONS CREATED BEFORE MULTI-ORG SUPPORT**

Existing single-organization integrations continue to work with no action required. Their organization appears as the only selected organization under **GitHub Organizations**, and previously synced data is preserved.
{% endhint %}

### Suspend auto-discovery <a href="#suspend-auto-discovery" id="suspend-auto-discovery"></a>

If auto-discovery is suspended, new entities will not appear in the **Discovered** tab. Existing imported entities remain unchanged in the catalog and the sync between GitHub and their corresponding IDP entities will stop.

To suspend auto-discovery:

1. Go to **Integrations** and open your GitHub integration using the **View** button.
2. Click **Configuration** at the top.
3. In the **Danger Zone** section, click **Suspend**.
4. Confirm the action.

You may re-enable it at any time by following the same steps.

***

## GitHub permissions <a href="#github-permissions" id="github-permissions"></a>

The GitHub Integration connector supports three credential types. The table below summarizes the minimum permissions required for each, and how many GitHub organizations a single integration can sync with it. Detailed breakdowns follow.

| Credential Type                    | Minimum Permission                                                                       | Organizations per integration |
| ---------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------- |
| Classic Personal Access Token      | `repo` scope, `read:org` scope + SSO authorization for each organization (if applicable) | Multiple                      |
| Fine-Grained Personal Access Token | Repository: Metadata (Read-only), Organization: Members (Read-only)                      | Single                        |
| GitHub App                         | Repository: Metadata (Read-only), Organization: Members (Read-only)                      | Single                        |

{% hint style="info" %}
**GITHUB ENTERPRISE SERVER (GHES) TOKENS**

Auth type, PAT scopes, and secret storage are identical to public GitHub. The only GHES-specific requirement is that the PAT must be created on the GHES instance, not on github.com. If the org uses SAML SSO, click **Configure SSO** next to the token and authorize it for each org you plan to sync, otherwise `read:org` calls return 404.
{% endhint %}

### Classic personal access token <a href="#classic-personal-access-token" id="classic-personal-access-token"></a>

The following scopes are required for IDP to perform org-level discovery of repositories and teams:

* `repo` - Required to read private repository information. Classic PATs on GitHub do not offer a read-only scope for private repositories, so this broader scope is necessary even though IDP only reads repository data.
* `read:org` (under admin:org) - Grants read access to organization and team membership, and org projects.

![Classic PAT scope selection with repo and read:org checked](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-500df0d20171b3bd5c5716dc091dbeb1cae63988%2Frepo-perm1-v2.png?alt=media)

If any GitHub organization you plan to sync enforces SAML SSO, the token must also be explicitly authorized for that organization after it is generated. Without SSO authorization, org-level queries for that organization will fail even if `read:org` is selected.

To authorize, navigate to your token on the GitHub tokens page, click **Configure SSO**, and click **Authorize** next to each organization you plan to select in the integration. Organizations that are already authorized show **Deauthorize** instead.

![Configure SSO dialog showing organizations available to authorize](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-fdd0ab310b45e6ec27dcedae8229d2e28a25b29b%2Frepo-perm2.png?alt=media)

### Fine-grained personal access token <a href="#fine-grained-personal-access-token" id="fine-grained-personal-access-token"></a>

* **Repository access** must be set to **All repositories** so that IDP can discover all repositories in the organization.

  ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-82febdd7d45dc7d13fbd46eb95466210f0bb930c%2Frepo-perm3a-v2.png?alt=media)
* Under the **Repositories** permission tab, set all the following options to `Read-only`:

  * `Contents`
  * `Issues`
  * `Metadata`
  * `Pull Requests`

  ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-f7646ec1d237a93e5c555d22b9faf3303146fe7e%2Frepo-perm3b-v3.png?alt=media)
* Under the **Organizations** permission tab, set `Members` to `Read-only`.

  ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-08f65eba7bd3ae03c87745b61ad3e9ac73eac256%2Frepo-perm4-v3.png?alt=media)

The **Resource owner** must be set to the **organization**, not a personal account. Fine-grained tokens are scoped to a single resource owner, so a connector that uses one can sync only one organization per integration. To sync multiple organizations, use a [Classic Personal Access Token](#classic-personal-access-token), or create a separate token, connector, and integration for each organization.

### GitHub app <a href="#github-app" id="github-app"></a>

* When configuring the app, the **Permissions** section should have the required permissions configured under both **Repository permissions** and **Organization permissions**.

  ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-1e17591c75a059067cc0720367ade60fadde112e%2Frepo-perm5-v3.png?alt=media)
* In **Repository permissions**, confirm that all the following options are set to `Read-only`:

  * `Contents`
  * `Issues`
  * `Metadata`
  * `Pull Requests`

  ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-a66d41b705b9bf43e203a9de816aa61849e1d8aa%2Frepo-perm6a-v3.png?alt=media)

  Similarly, under **Organization permissions**, set `Members` to `Read-only`.

  ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-a2afb00d1656dc10939321ed43e33ccb79b981e7%2Frepo-perm6b-v3.png?alt=media)
* The app must be installed on the organization for the permissions to take effect. Once installed, the app's permission summary on the org's installed apps page will confirm: `Read access to members and metadata`

  ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-aeba3d94d96410923f71fb13ac6c1e843ba27b3a%2Frepo-perm7.png?alt=media)

Each GitHub App installation is tied to a single organization, so a connector that uses a GitHub App can sync only one organization per integration. To sync multiple organizations from a single integration, use a [Classic Personal Access Token](#classic-personal-access-token) instead.

***

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

Select any issue below to expand it and view the cause and fix. The following covers common organization selection issues and GitHub Enterprise Server (GHES) failure modes.

<details>

<summary>GitHub integration sync completed but 0 records were ingested</summary>

The selected organizations contain no discoverable files, or, for GHES, the connector URL is missing the org path segment. Confirm the repos in each selected organization contain at least one file in the default branch root. For GHES, update the connector URL to `https://<ghes-host>/<org>`.

</details>

<details>

<summary>GitHub Enterprise Server integration INIT pod fails with ImagePullBackOff or 429 TOOMANYREQUESTS</summary>

The delegate hit the Docker Hub anonymous rate limit. Configure the `docker-connector` account setting to point at an authenticated Docker Hub connector.

</details>

<details>

<summary>Harness delegate cannot connect to the GitHub Enterprise Server host</summary>

The delegate egress cannot reach the GHES host. Verify reachability with `curl -I https://<ghes-host>`. If GHES is IP-allowlisted, request allowlisting for the delegate egress IP.

</details>

<details>

<summary>No data is synced from a selected organization, or read:org calls return 404</summary>

The classic PAT is not authorized for the organization under SAML SSO. On GitHub (or your GHES instance), click **Configure SSO** next to the token and click **Authorize** for each organization you plan to sync.

</details>

<details>

<summary>Only one organization appears in the Configure Organizations panel</summary>

The connector uses a fine-grained PAT or a GitHub App, which GitHub limits to a single organization. To select multiple organizations, switch to a connector that uses a classic PAT. If the connector already uses a classic PAT, confirm that the token's user is a member of the other organizations, then click **Refresh** in the panel.

</details>

<details>

<summary>An organization is missing from the Configure Organizations panel</summary>

The organization list may be out of date, or the organization is on another page. Click **Refresh**, then **Continue**, to refetch the list. The search field only searches the current page, so use **Next** to check the remaining pages.

</details>

{% @harness-feedback/feedback %}