GitHub Integration

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

The GitHub integration automatically discovers repositories, teams, and AI assets from your GitHub organization and brings them into the IDP Catalog. 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

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.

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.

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

The following are needed to get the integration running:

Ensure the feature flag IDP_INTEGRATIONS is enabled. Contact Harness Support to enable them.
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 or GitHub App Connector is configured in Harness with the credentials needed to access your GitHub organization. Ensure that the connector has the necessary permissions on your GitHub. You can create a new connector directly during the integration setup.
The connector's URL Type is set to Account, and the GitHub Account URL specifies your GitHub organization (for example, https://github.com/YOUR_ORG_NAME/). The integration requires an organization to run its org-level discovery queries against. Go to the GitHub connector settings reference to configure the URL Type and Account URL fields.
For each GitHub org, user has to maintain one integration.

GitHub Enterprise Server (GHES) prerequisites

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.

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

Enable the GitHub integration

1. Navigate to the integrations page

In Harness, open the Internal Developer Portal.
From the left sidebar, click Configure.
In the left navigation menu, click Integrations.
Figure 1: Navigation Path of GitHub Integration
On the Integrations page, click + New Integration at the top.
Select GitHub from the integration type picker. You will be taken to the Auto Discover GitHub Integration page.

2. Configure setup & connectivity

This section connects Harness IDP to your GitHub organization.

Figure 2: Setup & Connectivity

Enter a name in the Integration Name field. This name appears on the integration card on the Integrations page (e.g., GitHub Production).
Click the Choose GitHub connector dropdown and select the GitHub connector you want to use to pull data into the IDP.
CONNECTOR REQUIRES ORG-LEVEL PERMISSIONS
The GitHub integration performs org-level queries to discover repositories and teams across your organization. Ensure the GitHub connector you select has org-level permissions on your GitHub, and that its URL Type is Account with the GitHub Account URL set to your organization (for example, https://github.com/YOUR_ORG_NAME/).
DO NOT HAVE A GITHUB CONNECTOR YET?
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 GitHub connector URL determines everything downstream. Set it based on your GitHub type:
Scenario
Correct URL format
Do not use
Public GitHub, org scope
https://github.com/<org>
-
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
-
THE ORG PATH SEGMENT IS MANDATORY
Setting the connector URL to only the GHES host (for example, https://github.acme.com) causes the sync to fail with no records ingested. This is the same behavior as public GitHub without an org. Always include the org path segment: https://<ghes-host>/<org>.

3. Configure mapping & correlation

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 3: Available Entities - Repository, Team, and AI Assets

Repository entity

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

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.

Figure 4: Enable Repository Entity

Ensure the Repository Entity toggle is turned on.
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.
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
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.
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.
RELEASE DATA LIMIT
GitHub repository entities include release metadata for the latest 10 releases only (if they exist). Older releases are not ingested into the catalog.
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 5: Configure Secondary Kinds panel
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 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.
SECONDARY KINDS CANNOT BE CHANGED AFTER SETUP
These selections are locked once the integration is created and cannot be modified later. Choose carefully before confirming.
WHERE DOES THIS DATA APPEAR?
Secondary kinds data is surfaced on the Entity Details page for each repository. It does not appear in the Ingested Properties YAML in the Entity Inspector.

Team entity

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

Figure 6: Enable Team Entity

Ensure the Team Entity toggle is turned on.
Under Entity Registration Behavior, choose the registration behavior as described above for Repository Entity.
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
Configure the Correlation Mapping fields as needed.
Optionally, click Configure next to Configure fields (optional) to customize the field mapping.

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.

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 7: Enable AI Assets Entity

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

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.

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

Harness IDP includes out-of-the-box scorecard checks for AIAsset entities discovered through this integration. See Catalog Info YAML data source.

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 8: AI Assets Instructions

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:

Go to Configure → Layout in the IDP sidebar.
In Catalog Entities, click AI Asset.
Click Edit Layout.
Add the following definition (within tabs object) to your layout YAML:
```
- path: /instructions
  title: Instructions
  contents:
    - component: InstructionsTab
```
Figure 9: Edit Layout to display Instructions tab on Entity
Click Save.

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

The Instructions tab is currently supported for skill and agent type AI assets. Support for command type may be added in a future release.

4. Configure advanced settings

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

Figure 10: Advanced Settings

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.
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.
START DATE UPDATE LIMITS
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.
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 GitHub. Discovered repositories, teams, and AI assets appear in the Discovered tab.

Discover and import GitHub entities

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

Discovered tab

After the integration runs, all GitHub entities detected 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.

Figure 11: 'Discovered' tab showing GitHub Repositories, Teams, and AI Assets

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.

BULK IMPORT AND AUTO IMPORT OPTIONS

Bulk Import - Select services individually using the checkboxes, or use the snackbar at the bottom of the page to bulk-select by action type. Open the dropdown to choose All services, Register, or Merge (Recommended), then click Import selected services.
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.

Imported tab

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 12: 'Imported' tab showing GitHub entities linked to catalog entities

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.

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.

Events tab

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.

View GitHub entities in the catalog

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

To display GitHub data on the entity details 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.

From the left sidebar of IDP, go to Configure → Layout → Catalog Entities.
Edit the existing layout for your entity or create a new one.
Select the Entity Kind (e.g., component) and the Entity Type (e.g., service) that matches your imported GitHub entities.

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 13: Layout configuration for GitHub cards in Overview tab and Source Code tab

The relevant YAML additions are:

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

    - name: Source Code
      path: /source-code
      title: Source Code
      contents:
        - component: SourceControlTab

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

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.

Figure 14: GitHub Cards on the Overview tab

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

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 15: Source Code tab showing full GitHub resource details

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.

Ingested properties

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

Figure 16: Entity Inspector Page showing Ingested Properties

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

Edit the integration

To update the integration name, switch the GitHub connector, or change 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.

Suspend auto-discovery

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:

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

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

GitHub permissions

The GitHub Integration connector supports three credential types. The table below summarizes the minimum permissions required for each. Detailed breakdowns follow.

Credential Type

Minimum Permission

Classic Personal Access Token

repo scope, read:org scope + SSO authorization (if applicable)

Fine-Grained Personal Access Token

Repository: Metadata (Read-only), Organization: Members (Read-only)

GitHub App

Repository: Metadata (Read-only), Organization: Members (Read-only)

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.

Classic personal access token

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.

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

To authorize, navigate to your token on the GitHub tokens page, click Configure SSO, and authorize the token for the relevant organization.

Fine-grained personal access token

Repository access must be set to All repositories so that IDP can discover all repositories in the organization.
Under the Repositories permission tab, set the following options to Read-only:
- Contents
- Issues
- Metadata
- Pull Requests
Under the Organizations permission tab, set Members to Read-only.

The Resource owner must be set to the organization, not a personal account. Fine-grained tokens are scoped to a single resource owner, so one token covers one organization. If you need to connect multiple GitHub organizations, create a separate token and a separate Harness connector for each.

GitHub app

When configuring the app, the Permissions section should have the required permissions configured under both Repository permissions and Organization permissions.
In Repository permissions, confirm that the following options are set to Read-only:
- Contents
- Issues
- Metadata
- Pull Requests
Similarly, under Organization permissions, set Members to Read-only.
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

Troubleshooting

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

GitHub integration sync completed but 0 records were ingested

The connector URL is missing the org path segment, or the org contains no discoverable files. Update the URL to https://<host>/<org>. If the URL already includes the org, confirm the repos under that org contain at least one file in the default branch root.

GitHub Enterprise Server integration INIT pod fails with ImagePullBackOff or 429 TOOMANYREQUESTS

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

Harness delegate cannot connect to the GitHub Enterprise Server host

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.

GitHub Enterprise Server read:org calls return 404

The PAT is not authorized for the org under SAML SSO. Click Configure SSO next to the token on the GHES instance and authorize it for each org you plan to sync.

PreviousPagerDuty

NextSonarQube

Last updated 10 days ago

Was this helpful?