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

# GitHub Enterprise Cloud

> Connect a GitHub Enterprise Cloud data-residency tenant (*.ghe.com) with a tenant GitHub App so Bugzy can clone repositories, push branches, and open pull requests.

The GitHub Enterprise Cloud integration connects Bugzy to a GitHub Enterprise Cloud **data-residency** tenant — an instance hosted on your own regional subdomain such as `acme.ghe.com`. You register a GitHub App on your tenant and give Bugzy its credentials; the agent then enumerates the repositories the App can access, clones them, pushes branches, and opens pull requests against your tenant's API (`https://api.<your-host>`).

<Info>
  This integration is for GitHub Enterprise Cloud with **data residency** (`*.ghe.com`). If your organization is on standard `github.com`, use the [GitHub](/docs/integrations/github) integration instead — no separate connector is needed.
</Info>

## What GitHub Enterprise Cloud enables

* **Repository access** — Bugzy lists and clones every repository your tenant GitHub App is installed on
* **Branch push and pull requests** — session work is pushed as a branch and opened (or reused) as a pull request on your tenant
* **PR comments** — test results and findings posted back as pull request comments
* **Repo-hosted skills** — `SKILL.md` files under `.agents/skills/` in your repositories are loaded into agent sessions automatically

## Requirements

* A GitHub Enterprise Cloud tenant with data residency, reachable at `https://<your-subdomain>.ghe.com`
* A **GitHub App registered on your tenant** with the permissions below, installed on the repositories Bugzy should access
* The App's **App ID**, **Installation ID**, and **private key** (`.pem`)

### GitHub App permissions

Grant these repository permissions when you register the App. Contents read-only is not enough — pushing branches and opening pull requests requires **write**.

| Permission    | Access       | Purpose                                         |
| ------------- | ------------ | ----------------------------------------------- |
| Contents      | Read & write | Read code, push branches, commit test artifacts |
| Pull requests | Read & write | Open pull requests, post comments               |
| Issues        | Read & write | Track test-related issues                       |
| Metadata      | Read-only    | Repository metadata (granted automatically)     |

## Setup

<Steps>
  <Step title="Register a GitHub App on your tenant">
    On your tenant (`https://<your-subdomain>.ghe.com`), go to **Settings > Developer settings > GitHub Apps > New GitHub App**. Grant the repository permissions listed above.
  </Step>

  <Step title="Generate a private key">
    On the App's settings page, generate a private key and download the `.pem` file. Note the **App ID** shown at the top of the page.
  </Step>

  <Step title="Install the App">
    Install the App on the organization or repositories Bugzy should access. After installing, the **Installation ID** appears in the install page URL (`.../installations/<id>`).
  </Step>

  <Step title="Navigate to team integrations">
    In Bugzy, go to **Dashboard > \[Your Team] > Integrations** and find **GitHub Enterprise Cloud**.
  </Step>

  <Step title="Configure">
    Click **Configure**, then enter your **host** (for example `acme.ghe.com`), the **App ID**, the **Installation ID**, and paste the **private key**. Click **Save**. The private key is stored encrypted; the App ID and host are stored in plain text.
  </Step>
</Steps>

<Info>
  The API base is derived from your host — `acme.ghe.com` becomes `https://api.acme.ghe.com`. You never enter the API URL directly.
</Info>

## Inbound webhooks (@bugzy on PRs)

To let Bugzy react to activity on your tenant — for example an `@bugzy` mention in a pull request comment — register a webhook on your tenant GitHub App. Because each team connects its own tenant App, every connector has its **own webhook URL and secret**, both shown in the connector's **Configure** dialog once it is saved. If you just created the connector, reopen **Configure** after saving to copy them; connectors created before this feature may need one save to mint the secret before inbound webhooks can verify.

The webhook URL identifies your connector by a non-secret id:

```
https://<your-bugzy-host>/api/webhook/events?provider=github&connector=<connector-id>
```

<Steps>
  <Step title="Copy the URL and secret">
    Open **Configure** for the GitHub Enterprise Cloud connector. Under **Inbound webhooks**, copy the **Webhook URL** and **Webhook secret**.
  </Step>

  <Step title="Add a webhook on your tenant App">
    On your tenant GitHub App's settings page, open the **Webhook** section. Paste the URL as the **Payload URL** and the secret as the **Secret**, and set the content type to **application/json**.
  </Step>

  <Step title="Subscribe to events">
    A GitHub App decides what to deliver on its **Permissions & events** page (under **Subscribe to events**), not per-webhook. For the `@bugzy`-on-PR flow, subscribe to **Issue comment** — PR comments are delivered as `issue_comment` — plus **Pull request review** and **Pull request review comment** for review threads.
  </Step>
</Steps>

<Info>
  Saving the webhook sends a one-off `ping` (you'll see it verify with a `200` in **Recent Deliveries**); real activity only arrives once the App is subscribed to the events above. Bugzy reacts to newly **created** comments, so post a new `@bugzy` comment rather than editing an existing one.
</Info>

<Info>
  The webhook secret is generated once and stays stable across edits, so it keeps working after you update other fields. It is never regenerated when you edit the connector.
</Info>

## How pull requests work

When an agent session changes files in a repository, Bugzy pushes the work to a session branch and opens a pull request against the default branch. A follow-up turn on the same session updates the branch and reuses the open pull request instead of creating a new one.

## Editing the connection

Reopen **Configure** at any time to update the host, App ID, or Installation ID. Leave the private key field blank to keep the stored key, or paste a new `.pem` to rotate it.

## Limitations

* Data-residency tenants only (`*.ghe.com`) — standard `github.com` organizations use the [GitHub](/docs/integrations/github) integration
* Self-hosted **GitHub Enterprise Server** (your own hardware / VPC) is a separate, future connector and is not covered here
* Connects at the **team** level, not per project