If you want your GitHub App to be available to organizations in a GitHub Enterprise Server instance that you are not part of, you must take the following steps.
These steps are not required if your GitHub App will only be used by organizations in a GitHub Enterprise Server instance that you are part of. For more information, see "Installing your own GitHub App."
If GitHub Enterprise Server access is important, consider whether a custom action for GitHub Actions will suit your needs instead. Public actions are available on GitHub Enterprise Server instances with GitHub Connect. For more information, see "Enabling automatic access to GitHub.com actions using GitHub Connect."
Organizations owned by a GitHub Enterprise Server instance cannot install GitHub Apps registered on GitHub.com or on another GitHub Enterprise Server instance. Instead, they must register and install their own GitHub App for use on that instance.
The app developer shares the manifest or URL parameters with the GitHub Enterprise Server instance that wants to use the app. The same manifest or URL parameters can be shared with multiple GitHub Enterprise Server instances.
An organization owned by the instance uses the manifest or URL parameters to register a GitHub App.
The organization installs the GitHub App that they registered.
Optionally, if the organization made the GitHub App public, other organizations within the instance can install the GitHub App as well. There is not a way to install a GitHub App on an entire instance, only on organizations within an instance.
You app's code will need the credentials of the GitHub App that the GitHub Enterprise Server instance registered. It will also need the hostname of the instance. You have two options: get the credentials and hostname from the instance, or share the app code with the instance.
The instance can share their GitHub App credentials and hostname with the app developer. The instance should only do this if they trust the app developer. Then, the app code can use the appropriate credentials depending on what actions it is taking. The app developer must take precautions to use the appropriate set of credentials and to not leak data.
- The app developer controls the infrastructure that the app runs on.
- The app developer has more control over app updates.
- The app developer may have more insight into app performance.
- The app developer must take precautions to avoid leaking data from the instance.
The app developer can share the code for their app with the instance. Then, the instance can host the code on their own servers.
- The instance remains more secure because they aren't sharing their app credentials.
- The app developer doesn't need to worry about leaking data from the instance.
- The app developer relies on the instance to provide the infrastructure and set things up correctly.
- Releasing updates to the app code may be more complex.
- The app developer may lose visibility about app performance.
GitHub Enterprise Server uses different URLs than GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud. You should update your app code to use the appropriate URL depending on whether it is working with a GitHub Enterprise Server instance. Replace
HOSTNAME with the hostname of the GitHub Enterprise Server instance.
GitHub Enterprise Cloud
|GitHub Enterprise Server|
New REST API endpoints, GraphQL objects, and webhooks are released to GitHub Enterprise Server at a later date than GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud. Additionally, there are multiple versions of GitHub Enterprise Server, and older versions may have different REST API endpoints, GraphQL objects, and webhooks.
Therefore, the app code needs to be aware of these differences. API responses and webhook payloads include a
x-github-enterprise-version header for GitHub Enterprise Server payloads to help you determine what version you are handling.
Each GitHub Enterprise Server instance can configure its own rate limits. If your app is hitting a rate limit and is already taking precautions to stay under the rate limit, you should talk to the admin of the GitHub Enterprise Server instance.