Skip to content

GitHub Enterprise Apps docs #1211

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pjlast merged 6 commits into from
Jun 26, 2025
Merged

GitHub Enterprise Apps docs #1211

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a8d7954
Temp docs
pjlast May 14, 2025
80b20fd
Explain Enterprise Apps and syncing all installations
pjlast Jun 25, 2025
8f3f59b
Link to sections right from the start
pjlast Jun 25, 2025
fd355cd
Remove unnecessary blank line
pjlast Jun 25, 2025
5bc6d36
Remove comment
pjlast Jun 25, 2025
b30d891
Add note about client secret
pjlast Jun 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 48 additions & 4 deletions docs/admin/code_hosts/github.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,12 @@ There are 2 ways to connect with GitHub:

{/* <!-- NOTE: The instructions in the following sections closely mirror those in doc/admin/config/batch_changes under "Commit signing for GitHub". When making changes here, be sure to consider if those changes should also be made over there! --> */}

There are two ways to connect a GitHub App:
1. **[Create a new GitHub App](#creating-a-new-github-app)** via Sourcegraph, which will set up all of the required permissions and automatically retrieve the credentials
2. **[Add an existing GitHub App](#adding-an-existing-github-app)** by providing the details of an existing GitHub App (required when using GitHub Enterprise Apps)
Copy link
Copy Markdown
Member

@eseliger eseliger Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just wondering, is it theoretically possible to create a GHE App via the post method as well, we just don't support it right now?

Maybe we could look into that one day.

Copy link
Copy Markdown
Contributor Author

@pjlast pjlast Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing in the docs makes me believe that it's not possible, but the one customer that tried it (that we know of, at least) could not get it to work

Copy link
Copy Markdown
Member

@eseliger eseliger Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we probably don't post the form to the right endpoint or so, the enterprise GH Apps page is in a completely different place 😬

Copy link
Copy Markdown
Contributor Author

@pjlast pjlast Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll have a look! Maybe we can fix that


### Creating a new GitHub App

To create a GitHub App and connect it to Sourcegraph:

1. Go to **Site admin > Repositories > Github Apps** on Sourcegraph.
Expand Down Expand Up @@ -64,21 +70,29 @@ To create a GitHub App and connect it to Sourcegraph:

You can now [select repositories to sync](#selecting-repositories-to-sync) or see more configuration options in the [configuration section](#configuration).

#### Syncing repositories from all installations

When creating a code host connection for a GitHub App with multiple installations, you have two options:

1. **Sync from a specific installation**: Create a connection under a specific installation (as described above). This will only sync repositories from that particular installation.

2. **Sync from all installations**: Create a connection that syncs repositories from all installations of the GitHub App by omitting the `installationID` field in the connection configuration. This is useful when you want a single connection to handle repositories across multiple organizations or user accounts.

9. (Optional) If you want to sync repositories from other organization or user namespaces and your GitHub App is set to public visibility, you can create additional installations with **Add installation**.

> NOTE: When you create a GitHub App, Sourcegraph automatically sets up an [incoming webhook](/admin/config/webhooks/incoming) for the app. This webhook subscribes to events for any repository or organization the app has access to, allowing Sourcegraph to keep repository and permission data in sync with GitHub.

> NOTE: If you are using [Batch Changes](/batch-changes/), you can create a GitHub App to perform [commit signing](/admin/config/batch_changes#commit-signing-for-github) (Beta).

### Multiple installations
#### Multiple installations

The initial GitHub App setup will only install the App on the organization or user account that you registered it with. If your code is spread across multiple organizations or user accounts, you will need to create additional installations for each namespace that you want Sourcegraph to sync repositories from.

By default, Sourcegraph creates a private GitHub App, which only allows the App to be installed on the same organization or user account that it was created in. If you did not set the App to public visibility during creation, you will need to [change the visibility](https://docs.github.com/en/apps/maintaining-github-apps/modifying-a-github-app#changing-the-visibility-of-a-github-app) to public before you can install it in other namespaces. For security considerations, see [GitHub's documentation on private vs public apps](https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private).

Once public, App can be installed in additional namespaces either from Sourcegraph or from GitHub.

#### Installing from Sourcegraph
##### Installing from Sourcegraph

1. Go to **Site admin > Repositories > Github Apps** and click **Edit** on the App you want to install in another namespace. You'll be taken to the App details page.

Expand All @@ -99,7 +113,7 @@ Once public, App can be installed in additional namespaces either from Sourcegra

4. To sync repositories from this installation, click **Add connection** under your new installation.

#### Installing from GitHub
##### Installing from GitHub

1. Go to the GitHub App page. You can get here easily from Sourcegraph by clicking **View in GitHub** for the App you want to install in another namespace.
2. Click **Configure**, or go to **App settings > Install App**, and select the organization or user account you want to install the App on.
Expand All @@ -111,10 +125,40 @@ Once public, App can be installed in additional namespaces either from Sourcegra

5. To sync repositories from this installation, click **Add connection** under your new installation.

### Adding an existing GitHub App

If you have an existing GitHub App (such as a GitHub Enterprise App), you can connect it to Sourcegraph by providing its details manually. This is particularly useful for:

- **GitHub Enterprise Apps**: Apps that can be installed across multiple organizations within an enterprise account while maintaining private visibility
- **Existing GitHub Apps**: Apps that were created outside of Sourcegraph that you want to use for repository syncing

To add an existing GitHub App:

1. Go to **Site admin > Repositories > Github Apps** on Sourcegraph.
2. Click **Add an existing GitHub App**.
3. Enter the following details of your existing GitHub App:
- **GitHub URL**: The URL of your GitHub instance (e.g., `https://github.com` or `https://github-enterprise.example.com`)
- **Client ID**: The unique identifier for your GitHub App
- **Private Key**: The private key generated for your GitHub App (in PEM format)
4. Click **Add GitHub App** to save the configuration.
5. Once added, you can manage installations and create code host connections just like with apps created through Sourcegraph.
Copy link
Copy Markdown
Member

@eseliger eseliger Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we need to call out here what we provision for GitHub Apps usually, so the webhook events, token scopes, etc are sufficient? Plus creating a client id/secret pair and adding it to auth.providers


> NOTE: You'll still need to create a client secret on GitHub and [set up an auth provider](/admin/auth#github) if you would like to enable repository permissions.

When creating code host connections for your existing GitHub App, you can choose to sync repositories from a specific installation or from all installations by omitting the `installationID` field (see [Syncing repositories from all installations](#syncing-repositories-from-all-installations)).

> NOTE: For GitHub Enterprise Apps, this method allows you to use a single app across multiple organizations within your enterprise, avoiding the need to create separate public apps or multiple private apps for each organization.

> NOTE: Make sure your existing GitHub App has the required permissions listed in the [Creating a new GitHub App](#creating-a-new-github-app) section.

### Configuring Multiple Private GitHub Apps for Sourcegraph
If you prefer not to make your GitHub App public and instead create separate private GitHub Apps for each organizations, users will need to authorize each GitHub App individually to ensure proper repository access and permissions syncing. This is because GitHub Apps have narrowly scoped permissions and do not share authentication across multiple installations. To streamline this process, users can go to `User Settings` > `Account Security` in Sourcegraph and connect all necessary GitHub Apps from there. Once authorized, Sourcegraph will use the user's GitHub identity to determine access across all configured GitHub Apps.

For customers using GitHub Enterprise Cloud, an alternative approach is to create an Enterprise GitHub App, which can be installed across multiple organizations within an enterprise account while maintaining private visibility. More details on this approach can be found in [GitHub's documentation](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise).
**GitHub Enterprise Apps**: For customers using GitHub Enterprise Cloud, we recommend creating a GitHub Enterprise App, which can be installed across multiple organizations within an enterprise account while maintaining private visibility. This eliminates the need to create separate apps for each organization or make your app public.

To use a GitHub Enterprise App with Sourcegraph:
1. Create the Enterprise App in your GitHub Enterprise settings (see [GitHub's documentation](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise))
2. Use the [**Add an existing GitHub App**](#adding-an-existing-github-app) option in Sourcegraph to connect it

### Uninstalling an App

Expand Down