> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Enterprise Integration

> Connect a GitHub Enterprise Server or Enterprise Cloud (data residency) instance to ZeroPath for scans, PR checks, comments, and patch pull requests

## Overview

ZeroPath connects to **GitHub Enterprise** instances through a GitHub App that you create on your
own instance. Both deployment types are supported:

* **GitHub Enterprise Server (GHES)** — self-hosted, on a hostname you operate.
* **GitHub Enterprise Cloud with data residency** — GitHub-hosted, on a
  `your-tenant.ghe.com` subdomain.

Once connected, you can import repositories, run full scans, scan pull requests, post status checks
and inline comments, open patch pull requests for validated findings, and review dependency
findings on the **Dependencies** tab of [Issues](/docs/platform/issues) or on the
[Supply Chain page](https://zeropath.com/app/sca). These are the same capabilities ZeroPath provides
for GitHub.com.

You do not have to tell ZeroPath which type you have — enter your instance URL and it is detected
from the hostname, since the two use different GitHub API and web URL schemes.

The connection is set up with GitHub's [App Manifest flow](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest):
you enter your instance's URL in ZeroPath, review the app on your instance, and confirm its
creation. ZeroPath receives the app's credentials from your instance, stores them encrypted, and
installs the app on the organizations you choose. You never copy a client secret or private key by
hand.

<Note>
  GHES apps are isolated per instance. Each instance you connect gets its own app registration and
  its own encrypted credentials, so connecting one instance never affects another, and it never
  touches your GitHub.com connection.
</Note>

## Prerequisites

* A ZeroPath organization where you can create VCS installations and repositories.
* A GitHub Enterprise instance that is:
  * reachable from ZeroPath over **HTTPS** (plain HTTP is rejected), and
  * resolvable through **public DNS**.
* Permission on the instance to **create a GitHub App** (via the App Manifest flow) and to **install
  the app** on the target organization. If you cannot install apps directly, your installation
  request is sent to an organization owner for approval.
* **Enterprise Server only:** the ability to update your network allowlist / firewall so ZeroPath's
  egress IPs can reach your instance, and so your instance can deliver webhooks back to ZeroPath.
  See [Network and firewall](#network-and-firewall). Enterprise Cloud tenants are GitHub-hosted and
  publicly reachable, so there is nothing to allowlist.

## Connect GitHub Enterprise

<Steps>
  <Step title="Open the GitHub Enterprise setup">
    In ZeroPath, open the [Add a Repository](https://zeropath.com/app/repositories?m=AddRepos\&tab=ghes)
    dialog, select the **GHES** tab, and click **Set up GitHub Enterprise**.
  </Step>

  <Step title="Allow ZeroPath through your firewall (Enterprise Server only)">
    The setup dialog lists ZeroPath's egress source IPs. Add them to your network allowlist so
    ZeroPath can reach your instance's REST/GraphQL API, clone repositories, and so your instance can
    deliver webhooks to ZeroPath.

    <Note>
      If the egress IP list is not shown in your environment, contact
      [ZeroPath support](mailto:support@zeropath.com) for the current source IPs before continuing.
    </Note>

    The dialog hides this section once it detects a `.ghe.com` host — Enterprise Cloud is
    GitHub-hosted, so there is no firewall of yours in the path.
  </Step>

  <Step title="Enter your instance URL">
    Enter your GitHub Enterprise URL — `https://github.your-company.com` for Enterprise Server, or
    `https://your-tenant.ghe.com` for Enterprise Cloud with data residency. The dialog confirms
    which type it detected.

    The URL must be an HTTPS origin that resolves over public DNS. ZeroPath rejects `github.com` and
    its aliases, as well as hosts that resolve to private, loopback, or link-local addresses.

    <Note>
      For Enterprise Cloud, enter your **web** host (`your-tenant.ghe.com`), not the API host
      (`api.your-tenant.ghe.com`). ZeroPath derives the API host itself, and rejects the API host if
      you enter it rather than silently rewriting what you typed.
    </Note>
  </Step>

  <Step title="Choose how ZeroPath trusts your TLS certificate (Enterprise Server only)">
    Enterprise Cloud uses a GitHub-managed, publicly-trusted certificate, so this step is hidden for
    a `.ghe.com` host and a CA bundle is rejected if supplied.

    * **Publicly-trusted certificate** - the default. You do not need to provide anything else.
    * **Internal / self-signed** - paste or upload your CA bundle in PEM format. ZeroPath stores it
      encrypted and uses it only to verify TLS for your instance. ZeroPath always verifies
      certificates; it never disables validation.
  </Step>

  <Step title="Create the app on your instance">
    Click **Create app on your GitHub Enterprise**. ZeroPath sends you to your instance to create the
    `zeropath-scanner` GitHub App. Review the requested permissions and events (see
    [What the app can access](#what-the-app-can-access)), then confirm **Create GitHub App**.

    <Note>
      GitHub's manifest handshake is valid for one hour and can be used once. If you wait too long or
      navigate away, restart the flow from the setup dialog.
    </Note>
  </Step>

  <Step title="Install the app on your organization">
    After the app is created, ZeroPath sends you to your instance's app installation page. Select the
    organization whose repositories you want to scan and approve the installation.

    <Note>
      If you do not have permission to install the app, your request is sent to an organization owner
      for approval. Repositories appear once the owner approves it.
    </Note>
  </Step>

  <Step title="Wait for sync">
    You are redirected back to ZeroPath, and your GHES repositories begin syncing. They appear in the
    repository list on the **GHES** tab once ready.
  </Step>

  <Step title="Add repositories">
    Select the repositories to add and click **Add selected repositories**.
  </Step>
</Steps>

## What the app can access

ZeroPath creates the app with the same permission and event set as its first-party GitHub App, so
scanning behaves identically across GitHub.com and GitHub Enterprise Server.

The app requests these **permissions**:

| Permission | Access | Why |
| - | - | - |
| Metadata | Read | Baseline repository access |
| Contents | Write | Clone code; push patch branches |
| Pull requests | Write | Scan PRs, post comments, open patch PRs |
| Checks | Write | Post PR status checks |
| Issues | Write | Issue-based workflows and comments |
| Administration | Read | Enumerate repositories in an organization |
| Members | Read | Resolve organization membership |
| Merge queues | Read | Required to receive `merge_group` webhooks |
| Organization & repository custom properties / roles | Read | Repository classification and routing |

The app subscribes to these **webhook events**: `push`, `pull_request`, `pull_request_review`,
`pull_request_review_comment`, `pull_request_review_thread`, `issues`, `issue_comment`,
`merge_group`, `member`, `membership`, `organization`, `repository`, `team`, `team_add`, and
`custom_property_values`.

## Network and firewall

This section applies to **Enterprise Server**. Enterprise Cloud tenants are hosted by GitHub on the
public internet in both directions, so there is nothing for you to allowlist.

The connection needs traffic in **both** directions:

* **ZeroPath to your instance (outbound from ZeroPath).** ZeroPath calls your instance's REST and
  GraphQL APIs, clones repositories, and completes the manifest and OAuth handshakes. All of this
  originates from ZeroPath's egress IPs shown in the setup dialog. Allowlist them on your instance's
  firewall.
* **Your instance to ZeroPath (inbound to ZeroPath).** Your instance delivers webhook events to
  ZeroPath's public endpoint. Your instance must be able to reach ZeroPath over the public internet
  for PR scans and repository updates to trigger.

The API endpoints differ by deployment type, because GitHub serves them differently:

| | REST | GraphQL | Git clone |
| - | - | - | - |
| Enterprise Server | `https://<your-host>/api/v3` | `https://<your-host>/api/graphql` | `https://<your-host>` |
| Enterprise Cloud | `https://api.<your-tenant>.ghe.com` | `https://api.<your-tenant>.ghe.com/graphql` | `https://<your-tenant>.ghe.com` |

<Warning>
  ZeroPath must reach your instance over HTTPS at a publicly-resolvable DNS name. Instances that are
  only reachable on a private network, or whose hostname resolves to a private or loopback address,
  cannot be connected. This is enforced as an anti-SSRF safeguard.
</Warning>

### TLS certificates

If your instance presents a publicly-trusted certificate, no extra configuration is needed. If it
uses an internal or self-signed certificate, provide the CA bundle (PEM) during setup. ZeroPath
stores the bundle encrypted and trusts it only for connections to your instance. It does not alter
any global trust store, and certificate verification stays enabled throughout.

## Repository imports

ZeroPath discovers repositories from the organizations where the app is installed. Import them the
same way as other providers:

* **Single repository** - select one repository and add it.
* **Selected batch** - select multiple repositories and import them together.
* **All repositories** - the GHES tab has no add-all button. Click **Select All** to select every repository currently loaded in the list, then click **Add selected repositories**.

Imported repositories receive the same default scanner settings, tags, repository limits, audit
events, and repository-added notifications as other supported VCS providers.

## PR scanning

When a pull request is opened or updated on a connected repository, your instance delivers a webhook
to ZeroPath, which schedules a PR scan against the changed files. Results can include:

* A ZeroPath status check on the pull request.
* Inline review comments on affected diff lines.
* A PR summary comment with the scan result.
* Automatic resolution of stale comment threads when findings are fixed or triaged.

[Bot commands](/docs/scanning/bot-commands) work on GHES pull request comments the same way they do on
GitHub.com.

## Patch pull requests

When a finding is eligible for an automatic fix, ZeroPath can open a pull request on your instance
using the same patch workflow as other providers:

* Generate a patch branch.
* Commit the fix with the standard ZeroPath commit-message convention.
* Open a pull request targeting the original branch.
* Add summary context and link the patch PR back to the finding in ZeroPath.

## Multiple organizations and reconnecting

* **Multiple organizations on one instance** - the `zeropath-scanner` app is installable across
  organizations on your instance. Install it on each organization whose repositories you want to
  scan.
* **Reconnecting** - if you start setup again for an instance ZeroPath has already registered, it
  skips app creation and sends you straight to the installation page. If the previous app was deleted
  on your instance, ZeroPath registers a fresh one.

## Troubleshooting

<AccordionGroup>
  <Accordion title="ZeroPath rejects my instance URL">
    The URL must be HTTPS and resolve over public DNS. `github.com` and its aliases are rejected, as
    are hosts that resolve to private, loopback, link-local, or carrier-grade-NAT addresses. Confirm
    your instance has a public DNS name and a reachable HTTPS endpoint.
  </Accordion>

  <Accordion title="TLS / certificate errors during setup">
    If your instance uses an internal or self-signed certificate, choose **Internal / self-signed**
    and provide the full CA chain in PEM format. A partial chain (missing intermediates) is the most
    common cause of verification failures.
  </Accordion>

  <Accordion title="The app was created but no repositories appear">
    The app must be **installed** on an organization, not just created. Finish the installation step
    and select the target organization. If you lack install permission, an organization owner must
    approve the pending request before repositories sync.
  </Accordion>

  <Accordion title="'Create GitHub App' fails or the flow times out">
    GitHub's manifest handshake expires one hour after it starts and is single-use. Restart setup
    from the **GHES** tab to get a fresh handshake.
  </Accordion>

  <Accordion title="PR scans or repository updates do not trigger">
    Webhook events are delivered from your instance to ZeroPath's public endpoint. Confirm your
    instance can reach the public internet and that no egress firewall is blocking webhook delivery.
    Also confirm PR scanning is enabled in ZeroPath repository settings.
  </Accordion>

  <Accordion title="Statuses, comments, or patch PRs do not appear">
    These require the app's write permissions (checks, pull requests, contents) to remain granted on
    the target organization. Confirm the installation still holds those permissions, and that branch
    protection rules on your instance are not blocking automated branch updates.
  </Accordion>

  <Accordion title="Scan fails with a DNS, TLS, or connectivity error">
    If a scan fails because ZeroPath cannot reach your instance at clone time, the scan status shows
    a specific error — for example, host name not resolvable, TLS certificate verification failed,
    host unreachable, or clone timeout. Check the host name and network configuration described in
    [Network and firewall](#network-and-firewall) and [TLS certificates](#tls-certificates). If
    your instance's certificate or network changed after initial setup, update the connection
    settings accordingly.
  </Accordion>
</AccordionGroup>

## Operational notes

* Disconnecting a GHES installation stops new scans from being scheduled for that connection and
  removes the repositories linked through it. Repositories protected by researcher mode are retained
  until researcher mode is disabled.
* If you add new organizations after setup, install the app on them so ZeroPath can discover their
  repositories.
* GHES apps and credentials are scoped per instance and stored encrypted; connecting or
  disconnecting one instance does not affect any other instance or your GitHub.com connection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.