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

# GitHub Enterprise Server

> Comprehensive guide for connecting Factory with your GitHub Enterprise Server instance

Factory can connect to a self-hosted GitHub Enterprise Server (GHES) instance using OAuth, making your organization's GHES repositories available inside Factory. Setup is self-service: an admin registers an OAuth App on the GHES instance and enters its credentials in Factory.

This guide covers both the one-time **admin setup** and **day-to-day usage** for end users.

> Connecting to a GitHub Enterprise Server instance is only supported in the Enterprise plan.

## Part 1: Admin Setup (one-time)

### Prerequisites

* You are an **Owner/Manager** in your Factory organization (a privileged role is required to configure the integration).
* You have access to create an **OAuth App** on your GHES instance.
* Your GHES instance must have a **publicly reachable domain** and be accessible over the public internet. Factory validates that the server domain resolves to a public IP address. *(Note: If your instance is behind a proxy or firewall, please contact Factory Support to obtain the specific Factory IP addresses you will need to allowlist.)*

### Step 1: Create an OAuth App on GHES

<Steps>
  <Step title="Navigate to Developer Settings">
    In GHES, go to **Settings > Developer settings > OAuth Apps > New OAuth App** (you may create it under your personal account or under an organization you own).
  </Step>

  <Step title="Fill in Application Details">
    * **Application name**: e.g. `Factory Integration`
    * **Homepage URL**: your Factory URL (e.g., `https://app.factory.ai`)
    * **Authorization callback URL**: `https://<your-factory-api-domain>/api/integrations/redirect/github-es/callback`
      *(Note: If you use the Factory control plane, your API domain will be `api.factory.ai`)*
  </Step>

  <Step title="Generate Credentials">
    Register the app, then copy the **Client ID** and generate a **Client Secret**. Securely store the Client Secret.
  </Step>
</Steps>

### Step 2: Configure the integration in Factory

<Steps>
  <Step title="Enter Server Details">
    In Factory, open **Settings > Integrations** and choose **GitHub Enterprise Server**. Enter your GHES details:

    * **Server domain** (e.g. `https://github.your-company.com`)
    * **Client ID**
    * **Client Secret**
  </Step>

  <Step title="Save Configuration">
    Save the configuration. Factory will normalize and validate the domain.
  </Step>
</Steps>

### Step 3: Authorize

<Steps>
  <Step title="Start the Connection">
    Click to authorize the integration. You are redirected to your GHES instance to authorize the OAuth App.
    *(Requested scopes: **`repo`** and **`read:org`**)*
  </Step>

  <Step title="Import Repositories">
    After you approve, Factory imports the repositories the authorizing account can access. Note that Factory **only exposes org-level repositories**, not user-level (personal) repositories.
  </Step>
</Steps>

### Important security notes for admins

* **One authorization serves the whole org.** The connecting admin's OAuth authorization is stored at the organization level and used for all of your org's GHES operations in Factory.
* **Use a dedicated service account** as the connecting admin rather than a personal employee account. This avoids tying org-wide access to one person's account lifecycle and lets you bound which repositories are exposed.
* **Repository scope.** Factory only exposes organization-level repositories. Personal (user-level) repositories accessible to the authorizing account are not imported into Factory.
* **Token lifecycle.** If your OAuth App issues expiring tokens, Factory refreshes them automatically. If it issues non-expiring tokens, the authorization is long-lived. Revoking the authorization or rotating the client secret disconnects the integration for the whole org.
* **Network reachability.** Factory validates and pins the resolved public IP for GHES requests (SSRF protection), so the instance must have a publicly reachable domain and be publicly resolvable. If your organization uses a proxy, contact Factory support for the IP addresses you need to allowlist.

***

## Part 2: End-User Guide

### What you get

Once your admin has connected GHES, your organization's GHES repositories appear in Factory alongside your other repositories, and you can use them in sessions like any other repo.

### Accessing GHES repos

* GHES access is enabled **at the organization level**. You do **not** need to authorize GHES individually.
* Repositories are available to members of your Factory org for whom the GHES integration is enabled.

### Troubleshooting

* **A repo I expect is missing.** It may be excluded because its owner/org is not part of the connected account's visibility, or because it is a personal (user-level) repository, which Factory does not expose. Confirm with your admin.
* **GHES repos suddenly disappeared or auth is failing.** The organization's GHES authorization may have expired or been revoked. Ask your admin to reconnect the integration.

***

## FAQ

**Does each user authorize GHES separately?**
No. One admin authorization is shared org-wide; access is gated at the organization level.

**What permissions does Factory request?**
The `repo` and `read:org` OAuth scopes.

<Card title="Security and Compliance" icon="shield-check" href="https://trust.factory.ai">
  Visit Factory's Trust Center for compliance documents, certifications, and security resources
</Card>