Merge pull request #25693 from github/repo-sync

repo sync

Author: Octomerger

content/apps/creating-github-apps/setting-up-a-github-app/index.md

@@ -18,6 +18,7 @@ children:
   - /choosing-permissions-for-a-github-app
   - /using-webhooks-with-github-apps
   - /making-a-github-app-public-or-private
+  - /making-your-github-app-available-for-github-enterprise-server
   - /creating-a-github-app-from-a-manifest
   - /creating-a-github-app-using-url-parameters
   - /creating-a-custom-badge-for-your-github-app

content/apps/creating-github-apps/setting-up-a-github-app/making-your-github-app-available-for-github-enterprise-server.md

@@ -0,0 +1,83 @@
+---
+title: Making your GitHub App available for GitHub Enterprise Server
+shortTitle: Share with GHES
+intro: 'In order for {% data variables.product.prodname_ghe_server %} instances to use your {% data variables.product.prodname_github_app %}, you must take some additional steps.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+topics:
+  - GitHub Apps
+---
+
+## About developing {% data variables.product.prodname_github_app %}s for {% data variables.product.prodname_ghe_server %}
+
+If you want your {% data variables.product.prodname_github_app %} to be available to organizations in a {% data variables.product.prodname_ghe_server %} instance that you are not part of, you must take the following steps.
+
+These steps are not required if your {% data variables.product.prodname_github_app %} will only be used by organizations in a {% data variables.product.prodname_ghe_server %} instance that you are part of.
+
+## Each {% data variables.product.prodname_ghe_server %} instance must create their own {% data variables.product.prodname_github_app %}
+
+Organizations owned by a {% data variables.product.prodname_ghe_server %} instance cannot install {% data variables.product.prodname_github_app %}s registered on {% data variables.product.prodname_dotcom_the_website %} or on another {% data variables.product.prodname_ghe_server %} instance. Instead, they must create and install their own {% data variables.product.prodname_github_app %} for use on that instance.
+
+1. The app developer creates a manifest or URL parameters. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters)."
+1. The app developer shares the manifest or URL parameters with the {% data variables.product.prodname_ghe_server %} instance that wants to use the app. The same manifest or URL parameters can be shared with multiple {% data variables.product.prodname_ghe_server %} instances.
+1. An organization owned by the instance creates a {% data variables.product.prodname_github_app %} from the manifest or URL parameters.
+1. The organization installs the {% data variables.product.prodname_github_app %} that they created.
+
+   Optionally, if the organization made the {% data variables.product.prodname_github_app %} public, other organizations within the instance can install the {% data variables.product.prodname_github_app %} as well. There is not a way to install a {% data variables.product.prodname_github_app %} on an entire instance, only on organizations within an instance.
+
+## The app code must be able to access the {% data variables.product.prodname_github_app %} credentials for the instance
+
+You app's code will need the credentials of the {% data variables.product.prodname_github_app %} that the {% data variables.product.prodname_ghe_server %} instance created. 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.
+
+### Get the credentials from the {% data variables.product.prodname_ghe_server %} instance
+
+The instance can share their {% data variables.product.prodname_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.
+
+Advantages:
+
+- 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.
+
+Disadvantages:
+
+- The app developer must take precautions to avoid leaking data from the instance.
+
+### Share the app code with the {% data variables.product.prodname_ghe_server %} 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.
+
+Advantages:
+
+- 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.
+
+Disadvantages:
+
+- 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.
+
+## The app code must use the correct URLs
+
+{% data variables.product.prodname_ghe_server %} uses different URLs than {% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, and {% data variables.product.prodname_ghe_cloud %}. You should update your app code to use the appropriate URL depending on whether it is working with a {% data variables.product.prodname_ghe_server %} instance. Replace `HOSTNAME` with the hostname of the {% data variables.product.prodname_ghe_server %} instance.
+
+{% data variables.product.prodname_free_user %}<br>{% data variables.product.prodname_pro %}<br>{% data variables.product.prodname_team %}<br>{% data variables.product.prodname_ghe_cloud %} | {% data variables.product.prodname_ghe_server %}
+--- | ---
+`https://api.github.com` | `https://HOSTNAME/api/v3`
+`https://api.github.com/graphql` | `https://HOSTNAME/api/v3/graphql`
+`https://github.com/login/oauth/authorize` | `https://HOSTNAME/login/oauth/authorize`
+`https://github.com/login/oauth/access_token` | `https://HOSTNAME/login/oauth/access_token`
+
+## The app code must be aware of feature differences
+
+New REST API endpoints, GraphQL objects, and webhooks are released to {% data variables.product.prodname_ghe_server %} at a later date than {% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, and {% data variables.product.prodname_ghe_cloud %}. Additionally, there are multiple versions of {% data variables.product.prodname_ghe_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 {% data variables.product.prodname_ghe_server %} payloads to help you determine what version you are handling.
+
+## Each {% data variables.product.prodname_ghe_server %} instance can configure rate limits
+
+Each {% data variables.product.prodname_ghe_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 {% data variables.product.prodname_ghe_server %} instance.