Merge pull request github#35048 from github/repo-sync

Repo sync

content/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise.md

@@ -0,0 +1,47 @@
+---
+title: Creating GitHub Apps for your enterprise
+intro: 'Learn how to create a {% data variables.product.prodname_github_app %} for organizations within your enterprise.'
+versions:
+  feature: enterprise-apps-public-beta
+type: how_to
+topics:
+  - Enterprise
+permissions: Enterprise owners.
+shortTitle: Create a GitHub App
+---
+
+{% data reusables.apps.enterprise-apps-beta %}
+
+You can create a {% data variables.product.prodname_github_app %} under your enterprise account. The app can only be installed on organizations within your enterprise, and can only be authorized by members of your enterprise. The app can't be installed on user accounts.
+
+## Step 1: Registering a {% data variables.product.prodname_github_app %}
+
+To create a {% data variables.product.prodname_github_app %}, you must first register the app. See "[AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)."
+
+## Step 2: Building a {% data variables.product.prodname_github_app %}
+
+After registering a {% data variables.product.prodname_github_app %}, you will want to write code to make your {% data variables.product.prodname_github_app %} do something. For examples of how to write code, see:
+
+* "[AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/quickstart)"
+* "[AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events)"
+* "[AUTOTITLE](/apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app)"
+* "[AUTOTITLE](/apps/creating-github-apps/guides/building-a-cli-with-a-github-app)"
+* "[AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)"
+
+You should aim to follow best practices. See "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)."
+
+## Step 3: Authorizing or sharing your {% data variables.product.prodname_github_app %}
+
+Once your {% data variables.product.prodname_github_app %} is registered, you'll need to make it available to organizations in your enterprise, either through **authorization** or **installation**, depending on the app’s purpose.
+
+### Step 3a: Authorizing your {% data variables.product.prodname_github_app %}
+
+Some {% data variables.product.prodname_github_apps %}, like {% data variables.product.prodname_copilot_short %} extensions, require **authorization** but do not need to be installed on an organization. Users in your enterprise can authorize the app to access resources within organizations. However, the app will only have access to {% data variables.product.github %} resources where it is installed. See "[AUTOTITLE](/apps/using-github-apps/authorizing-github-apps)."
+
+### Step 3b: Sharing your {% data variables.product.prodname_github_app %} via an installation link
+
+For apps that require installation to function, you can provide organization owners with an installation link. Once the app is installed, it will have access to the organization's resources. See "[AUTOTITLE](/apps/sharing-github-apps/sharing-your-github-app#sharing-your-github-app-via-an-install-link)."
+
+## Step 4: Installing your {% data variables.product.prodname_github_app %} (if required)
+
+If your {% data variables.product.prodname_github_app %} requires installation (not just authorization), organization owners can use the install link to install the app on their organization. See "[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party)."

content/admin/managing-your-enterprise-account/index.md

@@ -10,5 +10,6 @@ children:
   - /creating-a-readme-for-an-enterprise
   - /deleting-an-enterprise-account
   - /changing-the-url-for-your-enterprise
+  - /creating-github-apps-for-your-enterprise
 shortTitle: Manage enterprise account
 ---

content/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps.md

@@ -25,14 +25,18 @@ A {% data variables.product.prodname_github_app %} is a type of integration that
 
 Common use cases for {% data variables.product.prodname_github_apps %} include:
 * Automating tasks or background processes
-* Supporting "Sign in with GitHub," which allows users to sign in with their {% data variables.product.prodname_dotcom %} account to provide their identity in your ecosystem
+* Supporting "Sign in with {% data variables.product.company_short %}," which allows users to sign in with their {% data variables.product.prodname_dotcom %} account to provide their identity in your ecosystem
 * As a developer tool, allowing users to work with {% data variables.product.prodname_dotcom %} by signing into your  {% data variables.product.prodname_github_app %}, which can then act on their behalf
 * Integrating your tool or external service with {% data variables.product.company_short %}
 
 Like {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} use OAuth 2.0 and can act on behalf of a user. Unlike {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} can also act independently of a user.
 
 {% data variables.product.prodname_github_apps %} can be installed directly on organizations and personal accounts and granted access to specific repositories. They come with built-in webhooks and narrow, specific permissions.
 
+{% ifversion enterprise-apps-public-beta %}
+You can also create an enterprise-owned {% data variables.product.prodname_github_app %} that can only be installed on organizations within your enterprise, and can only be authorized by members of your enterprise. For more information, see "[AUTOTITLE](/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise)."
+{% endif %}
+
 {% data reusables.apps.app_manager_role %}
 
 ## Building a {% data variables.product.prodname_github_app %}
@@ -43,7 +47,13 @@ Then, you need to write code to add functionality to your {% data variables.prod
 
 Once you have written the code for your {% data variables.product.prodname_github_app %}, your app needs to run somewhere. If your app is a website or web app, you might host your app on a server like [Azure App Service](https://azure.microsoft.com/products/app-service/). If your app is a client-side app, it might run on a user's device.
 
-In order to use your {% data variables.product.prodname_github_app %}, you must install the app on your organization or personal account. If your {% data variables.product.prodname_github_app %} is private, you can only install the {% data variables.product.prodname_github_app %} on the account that owns the app. If your {% data variables.product.prodname_github_app %} is public, other users and organizations can install your app. For more information, see "[AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app)" and "[AUTOTITLE](/apps/sharing-github-apps/sharing-your-github-app)."
+To use your {% data variables.product.prodname_github_app %}, you need to install it on your organization or personal account.
+
+* If your {% data variables.product.prodname_github_app %} is **private**, you can only install it on the account that owns the app.
+* If your {% data variables.product.prodname_github_app %} is **public**, other users and organizations can also install it.{% ifversion enterprise-apps-public-beta %}
+* If your {% data variables.product.prodname_github_app %} is owned by an **enterprise**, you can install it on any organization within that enterprise.{% endif %}
+
+For more information, see "[AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app)" and "[AUTOTITLE](/apps/sharing-github-apps/sharing-your-github-app)."
 
 ## Understanding what type of {% data variables.product.prodname_github_app %} to build
 

content/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps.md

@@ -25,8 +25,7 @@ You must keep private keys for {% data variables.product.prodname_github_apps %}
 To generate a private key:
 
 {% data reusables.apps.settings-step %}
-{% data reusables.user-settings.developer_settings %}
-{% data reusables.user-settings.github_apps %}
+{% data reusables.apps.enterprise-apps-steps %}
 1. Next to the {% data variables.product.prodname_github_app %} that you want to generate a private key for, click **Edit**.
 1. Under "Private keys", click **Generate a private key**.
 1. You will see a private key in PEM format downloaded to your computer. Make sure to store this file because GitHub only stores the public portion of the key. For more information about securely storing your key, see "[Storing private keys](#storing-private-keys)."

content/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens.md

@@ -33,8 +33,7 @@ If your refresh token expires before you use it, you can regenerate a user acces
 When you create your app, expiration of user access tokens is enabled unless you opt out. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)." You can also configure this setting after your app has been created.
 
 {% data reusables.apps.settings-step %}
-{% data reusables.user-settings.developer_settings %}
-{% data reusables.user-settings.github_apps %}
+{% data reusables.apps.enterprise-apps-steps %}
 1. Next to the {% data variables.product.prodname_github_app %} that you want to modify, click **Edit**.
 1. In the {% data variables.product.prodname_github_apps %} settings sidebar, click **Optional Features**.
 1. Next to "User-to-server token expiration", click **Opt-in** or **Opt-out**. This setting may take a couple of seconds to apply.

content/apps/creating-github-apps/registering-a-github-app/creating-a-custom-badge-for-your-github-app.md

@@ -35,8 +35,7 @@ For more information about badges for {% data variables.product.prodname_github_
 ## Creating a custom badge
 
 {% data reusables.apps.settings-step %}
-{% data reusables.user-settings.developer_settings %}
-{% data reusables.user-settings.github_apps %}
+{% data reusables.apps.enterprise-apps-steps %}
 {% data reusables.user-settings.modify_github_app %}
 1. Under "Display information", drag and drop an image from a local folder or click **Upload a logo** to select an image from your computer.
 1. Optionally, crop your image.

content/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private.md

@@ -32,7 +32,11 @@ If a {% data variables.product.prodname_github_app %} registration is owned by a
 
 {% ifversion fpt or ghec %}You can register a {% data variables.product.prodname_github_app %} under your personal account or organization and make it available for other organizations to install. You do not need an enterprise plan or an organization account to make your {% data variables.product.prodname_github_app %} available to an organization even if the organization is owned by an enterprise on {% data variables.product.prodname_ghe_cloud %}.{% endif %}
 
-If you want to make your app available to {% ifversion ghes %}other {% endif %}{% data variables.product.prodname_ghe_server %} instances, then you need to take additional steps. For more information, see "[AUTOTITLE](/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server)."
+{% ifversion enterprise-apps-public-beta %}
+Additionally, you can register a {% data variables.product.prodname_github_app %} under your enterprise. You can't make this app public, the app can only be installed on organizations within your enterprise, and can only be authorized by members of your enterprise.
+{% endif %}
+
+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, then you need to take additional steps. For more information, see "[AUTOTITLE](/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server)."
 
 If it is important for {% ifversion ghes %}other {% endif %}{% data variables.product.prodname_ghe_server %} users to be able to use your tool, consider using {% data variables.product.prodname_actions %} instead of a {% data variables.product.prodname_github_app %}. Public actions are available on {% data variables.product.prodname_ghe_server %} instances with GitHub Connect. For more information, see "[AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect)" and "[AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises){% ifversion ghes %}."{% else %}" in the {% data variables.product.prodname_ghe_server %} documentation.{% endif %}
 
@@ -45,3 +49,11 @@ Public {% data variables.product.prodname_github_apps %} have a landing page wit
 ### Private installation flow
 
 Private {% data variables.product.prodname_github_apps %} can only be installed on the user or organization account of the app owner. Limited information about the app will exist on a landing page for the app, but the **Install** button will only be available to organization owners and app managers for the organization that owns the app, or the personal account if the {% data variables.product.prodname_github_app %} is owned by an individual account.
+
+{% ifversion enterprise-apps-public-beta %}
+
+### Enterprise-owned installation flow
+
+Enterprise-owned {% data variables.product.prodname_github_apps %} can only be installed by organization owners of organizations within the enterprise by using the installation URL. The app can not be installed on user accounts.
+
+{% endif %}

content/apps/creating-github-apps/registering-a-github-app/registering-a-github-app.md

@@ -1,7 +1,7 @@
 ---
 title: Registering a GitHub App
 shortTitle: 'Register a {% data variables.product.prodname_github_app %}'
-intro: 'You can register a {% data variables.product.prodname_github_app %} under your personal account or under any organization you own.'
+intro: 'You can register a {% data variables.product.prodname_github_app %} under your personal account{% ifversion enterprise-apps-public-beta %}, any organization you own, or your enterprise {% else %} or under any organization you own{% endif %}.'
 redirect_from:
   - /early-access/integrations/creating-an-integration
   - /apps/building-integrations/setting-up-and-registering-github-apps/registering-github-apps
@@ -21,19 +21,26 @@ topics:
 
 ## About registering {% data variables.product.prodname_github_apps %}
 
-You can register a {% data variables.product.prodname_github_app %} under your personal account, under an organization that you own, or under an organization that has granted you permission to manage all apps owned by the organization. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-github-app-managers-in-your-organization)."
+You can register a {% data variables.product.prodname_github_app %} in a few different ways.
+
+* Under your **personal account**.
+* Under an **organization you own**.
+* Under an **organization** that has granted you permission to manage all its apps. See "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-github-app-managers-in-your-organization)."{% ifversion enterprise-apps-public-beta %}
+* Under your **enterprise**, but it can only be installed on organizations within the enterprise.
+
+  {% data reusables.apps.enterprise-apps-beta %}
+{% endif %}
 
 {% data reusables.apps.maximum-github-apps-allowed %}
 
 ## Registering a {% data variables.product.prodname_github_app %}
 
 {% data reusables.apps.settings-step %}
-{% data reusables.user-settings.developer_settings %}
-{% data reusables.user-settings.github_apps %}
-1. Click **New GitHub App**.
-1. Under "GitHub App name", enter a name for your app. You should choose a clear and short name. The name cannot be longer than 34 characters. Your app's name (converted to lowercase, with spaces replaced by `-`, and with special characters replaced) will be shown in the user interface when your app takes an action. For example, `My APp Näme` would display as `my-app-name`.
+{% data reusables.apps.enterprise-apps-steps %}
+1. Click **New {% data variables.product.prodname_github_app %}**.
+1. Under "{% data variables.product.prodname_github_app %} name", enter a name for your app. You should choose a clear and short name. The name cannot be longer than 34 characters. Your app's name (converted to lowercase, with spaces replaced by `-`, and with special characters replaced) will be shown in the user interface when your app takes an action. For example, `My APp Näme` would display as `my-app-name`.
 
-   The name must be unique across {% data variables.product.company_short %}. You cannot use same name as an existing GitHub account, unless it is your own user or organization name.
+   The name must be unique across {% data variables.product.company_short %}. You cannot use the same name as an existing {% data variables.product.company_short %} account, unless it is your own user or organization name.
 
 1. Optionally, under "Description", type a description of your app. Users and organizations will see this description when they install your app.
 1. Under "Homepage URL", type the full URL to your app's website. If you don’t have a dedicated URL and your app's code is stored in a public repository, you can use that repository URL. Or, you can use the URL of the organization or user that owns the app.
@@ -57,9 +64,9 @@ You can register a {% data variables.product.prodname_github_app %} under your p
 1. If you entered a webhook URL, under "SSL verification", select whether to enable SSL verification. {% data variables.product.company_short %} highly recommends that you enable SSL verification.
 1. Under "Permissions", choose the permissions that your app needs. For each permission, select the dropdown menu and click **Read-only**, **Read & write**, or **No access**. You should select the minimum permissions necessary for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
 1. If you selected **Active** in the earlier step to indicate that your app should receive webhook events, under "Subscribe to events", select the webhook events that you want your app to receive. The permissions that you selected in the previous step determine what webhook events are available. For more information about each webhook event, see "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads)."
-1. Under "Where can this GitHub App be installed?", select  **Only on this account** or **Any account**.{% ifversion ghec %} If you use {% data variables.product.prodname_emus %}, **Only on this account** will be disabled for user accounts. Instead of **Any account**, the option will read **This enterprise**.{% endif %} For more information on installation options, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private)."
-
-1. Click **Create GitHub App**.
+1. Under "Where can this {% data variables.product.prodname_github_app %} be installed?", select  **Only on this account** or **Any account**.{% ifversion ghec %} If you use {% data variables.product.prodname_emus %}, **Only on this account** will be disabled for user accounts. Instead of **Any account**, the option will read **This enterprise**.{% endif %} For more information on installation options, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private)."{% ifversion enterprise-apps-public-beta %}
+    >[!NOTE] If your {% data variables.product.prodname_github_app %} is registered under an enterprise, this step does not apply.{% endif %}
+1. Click **Create {% data variables.product.prodname_github_app %}**.
 
 ## Next steps
 

content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app.md

@@ -45,8 +45,7 @@ This tutorial assumes that you have a basic understanding of Ruby. For more info
 You will need your app's client ID in order to generate a user access token via the device flow.
 
 {% data reusables.apps.settings-step %}
-{% data reusables.user-settings.developer_settings %}
-{% data reusables.user-settings.github_apps %}
+{% data reusables.apps.enterprise-apps-steps %}
 1. Next to the {% data variables.product.prodname_github_app %} that you want to work with, click **Edit**.
 1. On the app's settings page, find the client ID for your app. You will use it later in this tutorial. Note that the client ID is different from the app ID.