> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/code-hosting-platforms/github/github-enterprise-server.md).

# Connect your own GitHub App

Use your own GitHub App instead of the Swarmia app from the GitHub Marketplace. This works with

* **GitHub.com**: when your organization requires apps it owns and controls
* **GitHub Enterprise Cloud with data residency**: instances at `your-company.ghe.com`
* **GitHub Enterprise Server**: self-hosted instances, for example `github.your-company.com`

The setup is the same for all three. You'll create the app in GitHub, enter its credentials in Swarmia, and install it on your organization.

{% hint style="info" %}
You need Swarmia admin to enter the app credentials, and a GitHub organization owner (or an app manager) to create and install the app.
{% endhint %}

### 1. Start the setup in Swarmia

In Swarmia, go to [**Code hosting settings**](https://app.swarmia.com/settings/version-control) and select **Connect custom GitHub App**. Step 1 of the dialog shows the URLs you'll need in GitHub:

* **Callback URL**: `https://app.swarmia.com/auth/github/callback/<app key>`
* **Webhook URL**: `https://hook.swarmia.com/GithubWebhook`

The app key is generated for your organization. It's also part of your login URL, so keep the dialog open while you create the app.

### 2. Create the GitHub App

Create the app **under the GitHub organization you'll install it on**:

* **GitHub.com and data residency**: organization **Settings → Developer settings → GitHub Apps → New GitHub App**
* **Enterprise Server**: the same path on your instance, at `https://<hostname>/organizations/<org>/settings/apps/new`

#### General

| Field           | Value                      |
| --------------- | -------------------------- |
| GitHub App name | `Swarmia` (any name works) |
| Homepage URL    | `https://www.swarmia.com`  |

#### Identifying and authorizing users

Add **two** redirect URIs. Select **Add redirect URI** for the second one.

1. `https://app.swarmia.com/auth/github/callback/<app key>`: copy this from the Swarmia dialog.
2. `https://app.swarmia.com/auth/github/connect/callback`: users link their GitHub account through it.

Keep the first URI at the top of the list. Leave **Allow wildcard matching** unchecked on both.

* **Expire user authorization tokens**: ✅
* **Request user authorization (OAuth) during installation**: ✅
* **Enable Device Flow**: leave unchecked

#### Post installation

Leave **Setup URL** empty. GitHub disables it when OAuth is requested during installation.

#### Webhook

* **Active**: ✅
* **Webhook URL**: `https://hook.swarmia.com/GithubWebhook`
* **Secret**: a long random string, for example from `openssl rand -hex 32`. GitHub won't show it again, so save it now. You'll enter it in Swarmia.
* **SSL verification**: Enable SSL verification

#### Permissions

Set these and leave everything else at **No access**.

**Repository permissions**

| Permission      | Access         | Used for                                              |
| --------------- | -------------- | ----------------------------------------------------- |
| Actions         | Read-only      | CI and workflow run insights                          |
| Administration  | Read-only      | Repository teams and collaborators                    |
| Checks          | Read-only      | CI and check run insights                             |
| Commit statuses | Read-only      | CI status insights                                    |
| Contents        | Read-only      | Commits, branches, and releases                       |
| Deployments     | Read-only      | Deployment insights                                   |
| Issues          | Read-only      | GitHub Issues                                         |
| Metadata        | Read-only      | Mandatory, selected automatically                     |
| Projects        | Read-only      | Classic repository projects                           |
| Pull requests   | Read and write | Pull request data and Swarmia's pull request comments |

**Organization permissions**

| Permission                   | Access    | Used for                           |
| ---------------------------- | --------- | ---------------------------------- |
| Members                      | Read-only | Organization members and teams     |
| Projects                     | Read-only | GitHub Projects boards             |
| GitHub Copilot Business      | Read-only | Copilot seats (optional)           |
| Organization Copilot metrics | Read-only | Copilot usage metrics (optional)   |
| Administration               | Read-only | Copilot AI credit usage (optional) |

GitHub Enterprise Server doesn't offer the Copilot permissions. Leave them out there.

**Account permissions**: none.

#### Subscribe to events

The available events depend on the permissions above, so set the permissions first. Then select:

* Check run
* Deployment status
* Issue comment
* Issues
* Label
* Membership
* Organization
* Projects v2
* Projects v2 item
* Pull request
* Pull request review
* Pull request review comment
* Push
* Repository
* Status
* Sub issues
* Team
* Workflow run

#### Where can this GitHub App be installed?

* **Only on this account** (recommended): the app stays private, and only the organization that owns it can install it.
* **Any account**: only on GitHub Enterprise Server, if you need to install the app on several organizations on your instance. See Multiple GitHub organizations.

Select **Create GitHub App**.

#### Generate the credentials

On the app's **General** page:

1. Copy the **App ID** and **Client ID** shown at the top.
2. Under **Client secrets**, select **Generate a new client secret** and copy it. GitHub shows it only once.
3. Under **Private keys**, select **Generate a private key**. A `.pem` file is downloaded.

Optionally, upload a logo under **Display information**: light background, dark background.

### 3. Enter the credentials in Swarmia

Continue to step 2 of the Swarmia dialog and fill in:

| Swarmia field   | Where to find it in GitHub                                                  |
| --------------- | --------------------------------------------------------------------------- |
| GitHub hostname | `github.com`, `your-company.ghe.com`, or your Enterprise Server hostname    |
| App ID          | **General → About → App ID**                                                |
| Client ID       | **General → About → Client ID**                                             |
| Client secret   | The secret you generated under **Client secrets**                           |
| Webhook secret  | The secret you set under **Webhook → Secret**                               |
| Private key     | The full contents of the `.pem` file, including the `BEGIN` and `END` lines |

Select **Confirm**.

If you use a self-signed TLS certificate on GitHub Enterprise Server, contact Swarmia support before this step.

### 4. Allow network access (Enterprise Server only)

If your GitHub Enterprise Server is behind a firewall, allow:

* **Inbound** (Swarmia calls your GitHub API): `34.89.165.89` and `35.234.103.84`
* **Outbound** (GitHub sends webhooks to Swarmia): `34.117.202.112` (hook.swarmia.com) and `34.107.207.241` (app.swarmia.com)

If you can't allow inbound traffic, use the proxy agent and select it in the Swarmia dialog.

### 5. Install the app

In GitHub, open the app's settings, select **Install App**, and choose your organization and repositories:

* **GitHub.com and data residency**: `https://<hostname>/apps/<app-slug>/installations/new`
* **Enterprise Server**: `https://<hostname>/github-apps/<app-slug>`

Swarmia starts importing data as soon as the app is installed. You can follow the progress in **Settings → Version control**.

### Troubleshooting

* **"The redirect\_uri is not associated with this application"**: one of the two redirect URIs is missing. See Identifying and authorizing users.
* **Nothing appears after installing**: check the app's **Advanced → Recent Deliveries** in GitHub. Failed deliveries usually mean a wrong webhook URL or a webhook secret that doesn't match the one in Swarmia.
* **"Swarmia can only be installed in GitHub organization accounts"**: the app was installed on a personal account. Install it on an organization instead.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.swarmia.com/settings/integrations/code-hosting-platforms/github/github-enterprise-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.