From f5425021a447a4089fb8eabb2e924d7b238ef7d5 Mon Sep 17 00:00:00 2001 From: Sophie <29382425+sophietheking@users.noreply.github.com> Date: Tue, 22 Oct 2024 22:15:04 +0200 Subject: [PATCH] Enterprise-owned GitHub Apps [Public Beta] (#52580) Co-authored-by: Felix Guntrip Co-authored-by: Hirsch Singhal <1666363+hpsin@users.noreply.github.com> Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com> --- ...reating-github-apps-for-your-enterprise.md | 47 +++++++++++++ .../managing-your-enterprise-account/index.md | 1 + .../about-creating-github-apps.md | 14 +++- .../managing-private-keys-for-github-apps.md | 3 +- .../refreshing-user-access-tokens.md | 3 +- ...ting-a-custom-badge-for-your-github-app.md | 3 +- .../making-a-github-app-public-or-private.md | 14 +++- .../registering-a-github-app.md | 27 ++++--- .../building-a-cli-with-a-github-app.md | 3 +- ...hub-app-that-responds-to-webhook-events.md | 18 ++--- ...in-with-github-button-with-a-github-app.md | 29 ++++---- .../building-ci-checks-with-a-github-app.md | 12 ++-- .../quickstart.md | 10 +-- ...our-app-listing-from-github-marketplace.md | 4 +- .../deleting-a-github-app.md | 11 ++- ...g-allowed-ip-addresses-for-a-github-app.md | 5 +- .../modifying-a-github-app-registration.md | 29 ++++---- .../transferring-ownership-of-a-github-app.md | 14 ++-- ...vating-optional-features-for-oauth-apps.md | 2 +- ...egistering-a-github-app-from-a-manifest.md | 70 +++++++++---------- ...ering-a-github-app-using-url-parameters.md | 8 ++- .../sharing-your-github-app.md | 7 +- .../authorizing-github-apps.md | 2 +- ...talling-a-github-app-from-a-third-party.md | 14 ++-- .../installing-your-own-github-app.md | 14 ++-- ...-your-github-app-for-your-copilot-agent.md | 3 +- ...a-github-app-for-your-copilot-extension.md | 3 +- .../redelivering-webhooks.md | 3 +- .../viewing-webhook-deliveries.md | 9 ++- .../using-webhooks/creating-webhooks.md | 3 +- .../using-webhooks/disabling-webhooks.md | 3 +- data/features/enterprise-apps-public-beta.yml | 6 ++ data/reusables/apps/enterprise-apps-beta.md | 1 + data/reusables/apps/enterprise-apps-steps.md | 8 +++ .../apps/settings-step-personal-orgs.md | 6 ++ data/reusables/apps/settings-step.md | 7 +- 36 files changed, 260 insertions(+), 156 deletions(-) create mode 100644 content/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise.md create mode 100644 data/features/enterprise-apps-public-beta.yml create mode 100644 data/reusables/apps/enterprise-apps-beta.md create mode 100644 data/reusables/apps/enterprise-apps-steps.md create mode 100644 data/reusables/apps/settings-step-personal-orgs.md diff --git a/content/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise.md b/content/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise.md new file mode 100644 index 000000000000..beec26003881 --- /dev/null +++ b/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)." diff --git a/content/admin/managing-your-enterprise-account/index.md b/content/admin/managing-your-enterprise-account/index.md index 9ad427f72c99..8eb3b1f6e595 100644 --- a/content/admin/managing-your-enterprise-account/index.md +++ b/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 --- diff --git a/content/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps.md b/content/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps.md index 98dab9c08361..bc6ef0a8d2f0 100644 --- a/content/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps.md +++ b/content/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps.md @@ -25,7 +25,7 @@ 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 %} @@ -33,6 +33,10 @@ Like {% data variables.product.prodname_oauth_apps %}, {% data variables.product {% 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 diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps.md index ec2fec15f5c4..7bdcf49b81d8 100644 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps.md +++ b/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)." diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens.md index 877136f9fee4..f03912991260 100644 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens.md +++ b/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. diff --git a/content/apps/creating-github-apps/registering-a-github-app/creating-a-custom-badge-for-your-github-app.md b/content/apps/creating-github-apps/registering-a-github-app/creating-a-custom-badge-for-your-github-app.md index 823ae9033bc9..341b1dd1fb41 100644 --- a/content/apps/creating-github-apps/registering-a-github-app/creating-a-custom-badge-for-your-github-app.md +++ b/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. diff --git a/content/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private.md b/content/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private.md index 63b929f275cb..f1a3b46b631b 100644 --- a/content/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private.md +++ b/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 %} diff --git a/content/apps/creating-github-apps/registering-a-github-app/registering-a-github-app.md b/content/apps/creating-github-apps/registering-a-github-app/registering-a-github-app.md index f5906fd733f8..0bb8cdccf0ba 100644 --- a/content/apps/creating-github-apps/registering-a-github-app/registering-a-github-app.md +++ b/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 diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app.md index d83b0a90f651..dddc948c7203 100644 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app.md +++ b/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. diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events.md index 67f6b1e3b19c..5c6bb6fef495 100644 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events.md +++ b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events.md @@ -40,9 +40,9 @@ This tutorial assumes you have a basic understanding of JavaScript and ES6 synta The following sections will lead you through setting up the following components: -* a repository to store the code for your app -* a way to receive webhooks locally -* a {% data variables.product.prodname_github_app %} registration that is subscribed to "pull request" webhook events, has permission to add comments to pull requests, and uses a webhook URL that you can receive locally +* A repository to store the code for your app +* A way to receive webhooks locally +* A {% data variables.product.prodname_github_app %} registration that is subscribed to "pull request" webhook events, has permission to add comments to pull requests, and uses a webhook URL that you can receive locally ### Create a repository to store code for your app @@ -73,10 +73,9 @@ For this tutorial, you must have a {% data variables.product.prodname_github_app The following steps will guide you through registering a {% data variables.product.prodname_github_app %} with these settings. For more information about {% data variables.product.prodname_github_app %} settings, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-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. For example, `USERNAME-webhook-test-app` where `USERNAME` is your {% data variables.product.company_short %} username. +{% 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. For example, `USERNAME-webhook-test-app` where `USERNAME` is your {% data variables.product.company_short %} username. 1. Under "Homepage URL", enter a URL for your app. For example, you can use the URL of the repository that you created to store the code for your app. 1. Skip the "Identifying and authorizing users" and "Post installation" sections for this tutorial. For more information about these settings, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)." 1. Make sure that **Active** is selected under "Webhooks." @@ -84,8 +83,9 @@ The following steps will guide you through registering a {% data variables.produ 1. Under "Webhook secret", enter a random string. You will use this string later. 1. Under "Repository permissions", next to "Pull requests," select **Read & write**. 1. Under "Subscribe to events", select **Pull request**. -1. Under "Where can this GitHub App be installed?", select **Only on this account**. You can change this later if you want to publish your app. -1. Click **Create GitHub App**. +1. Under "Where can this {% data variables.product.prodname_github_app %} be installed?", select **Only on this account**. You can change this later if you want to publish your app.{% 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 %}**. ## Write code for your app diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app.md index 84c0fa96bbb2..1591f392b521 100644 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app.md +++ b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app.md @@ -15,7 +15,7 @@ redirect_from: ## Introduction -This tutorial demonstrates how to build a "Login with GitHub" button for a website. The website will use a {% data variables.product.prodname_github_app %} to generate a user access token via the web application flow. Then, the website uses the user access token to make API requests on behalf of the authenticated user. +This tutorial demonstrates how to build a "Login with {% data variables.product.github %}" button for a website. The website will use a {% data variables.product.prodname_github_app %} to generate a user access token via the web application flow. Then, the website uses the user access token to make API requests on behalf of the authenticated user. This tutorial uses Ruby, but you can use the web application flow with any programming language that is used for web development. @@ -74,8 +74,7 @@ To follow this tutorial, you must install the Sinatra and dotenv gems in your Ru This tutorial will show you how to store the client ID and client secret in environment variables and access them with `ENV.fetch`. When you deploy your app, you will want to change how you store the client ID and client secret. For more information, see "[Securely store your client secret](#securely-store-your-client-secret)." {% 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 add it to a `.env` file in a following step. Note that the client ID is different from the app ID. 1. On the app's settings page, click **Generate a new client secret**. You will add the client secret to a `.env` file in a following step. @@ -161,13 +160,13 @@ These steps lead you through writing code to generate a user access token. To sk ``` 1. In your terminal, from the directory where `app.rb` is stored, run `ruby app.rb`. A local Sinatra server should start. - 1. In your browser, navigate to `http://localhost:4567`. You should see a link with the text "Login with GitHub". - 1. Click on the "Login with GitHub" link. + 1. In your browser, navigate to `http://localhost:4567`. You should see a link with the text "Login with {% data variables.product.github %}". + 1. Click on the "Login with {% data variables.product.github %}" link. - If you have not authorized the app, clicking on the link should take you to `{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=CLIENT_ID`, where `CLIENT_ID` is the client ID of your app. This is a GitHub page that prompts users to authorize your app. If you click the button to authorize your app, you will go to the callback URL for your app. + If you have not authorized the app, clicking on the link should take you to `{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=CLIENT_ID`, where `CLIENT_ID` is the client ID of your app. This is a {% data variables.product.github %} page that prompts users to authorize your app. If you click the button to authorize your app, you will go to the callback URL for your app. If you previously authorized your app and the authorization has not been revoked, you will skip the authorization prompt and go directly to the callback URL instead. You can revoke your previous authorization if you want to see the authorization prompt. For more information, see "[AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations)." - 1. The callback URL page, reached by clicking the "Login with GitHub" link and then authorizing the app if prompted to do so, should display the text similar to "Successfully authorized! Got code agc622abb6135be5d1f2." + 1. The callback URL page, reached by clicking the "Login with {% data variables.product.github %}" link and then authorizing the app if prompted to do so, should display the text similar to "Successfully authorized! Got code agc622abb6135be5d1f2." 1. In your terminal where Sinatra is running, stop the server by entering Ctrl+C. 1. Replace the content of `app.rb` with the following code, where `CALLBACK_URL` is the callback URL for your app, minus the domain. @@ -237,10 +236,10 @@ These steps lead you through writing code to generate a user access token. To sk 1. Optionally, check your progress: 1. In your terminal, from the directory where `app.rb` is stored, run `ruby app.rb`. A local Sinatra server should start. - 1. In your browser, navigate to `http://localhost:4567`. You should see a link with the text "Login with GitHub". - 1. Click on the "Login with GitHub" link. + 1. In your browser, navigate to `http://localhost:4567`. You should see a link with the text "Login with {% data variables.product.github %}". + 1. Click on the "Login with {% data variables.product.github %}" link. 1. If prompted to do so, authorize your app. - 1. The callback URL page, reached by clicking the "Login with GitHub" link and then authorizing the app if prompted to do so, should display the text similar to "Successfully authorized! Got code 4acd44861aeda86dacce and exchanged it for a user access token ending in 2zU5kQziE." + 1. The callback URL page, reached by clicking the "Login with {% data variables.product.github %}" link and then authorizing the app if prompted to do so, should display the text similar to "Successfully authorized! Got code 4acd44861aeda86dacce and exchanged it for a user access token ending in 2zU5kQziE." 1. In your terminal where Sinatra is running, stop the server by entering Ctrl+C. 1. Now that you have a user access token, you can use the token to make API requests on behalf of the user. For example: @@ -264,7 +263,7 @@ These steps lead you through writing code to generate a user access token. To sk end ``` - Update the callback handler to call the `user_info` function and to display the user's name and GitHub login. Remember to replace `CALLBACK_URL` with the callback URL for your app, minus the domain. + Update the callback handler to call the `user_info` function and to display the user's name and {% data variables.product.github %} login. Remember to replace `CALLBACK_URL` with the callback URL for your app, minus the domain. ```ruby copy get "CALLBACK_URL" do @@ -377,14 +376,14 @@ end This tutorial assumes that your app code is stored in a file named `app.rb` and that you are using the default URL for a local Sinatra application, `http://localhost:4567`. 1. In your terminal, from the directory where `app.rb` is stored, run `ruby app.rb`. A local Sinatra server should start. -1. In your browser, navigate to `http://localhost:4567`. You should see a link with the text "Login with GitHub". -1. Click on the "Login with GitHub" link. +1. In your browser, navigate to `http://localhost:4567`. You should see a link with the text "Login with {% data variables.product.github %}". +1. Click on the "Login with {% data variables.product.github %}" link. - If you have not authorized the app, clicking on the link should take you to `{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=CLIENT_ID`, where `CLIENT_ID` is the client ID of your app. This is a GitHub page that prompts users to authorize your app. If you click the button to authorize your app, you will go to the callback URL for your app. + If you have not authorized the app, clicking on the link should take you to `{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=CLIENT_ID`, where `CLIENT_ID` is the client ID of your app. This is a {% data variables.product.github %} page that prompts users to authorize your app. If you click the button to authorize your app, you will go to the callback URL for your app. If you previously authorized your app and the authorization has not been revoked, you will skip the authorization prompt and go directly to the callback URL instead. You can revoke your previous authorization if you want to see the authorization prompt. For more information, see "[AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations)." -1. The callback URL page, reached by clicking the "Login with GitHub" link and then authorizing the app if prompted to do so, should display the text similar to "Successfully authorized! Welcome, Mona Lisa (octocat)." +1. The callback URL page, reached by clicking the "Login with {% data variables.product.github %}" link and then authorizing the app if prompted to do so, should display the text similar to "Successfully authorized! Welcome, Mona Lisa (octocat)." 1. In your terminal where Sinatra is running, stop the server by entering Ctrl+C. ## Next steps diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app.md index f7a38df91aac..a65267c8c820 100644 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app.md +++ b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app.md @@ -142,10 +142,9 @@ For this tutorial, you must register a {% data variables.product.prodname_github The following steps will guide you through configuring a {% data variables.product.prodname_github_app %} with these settings. For more information about {% data variables.product.prodname_github_app %} settings, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-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. For example, `USERNAME-ci-test-app` where `USERNAME` is your {% data variables.product.company_short %} username. +{% 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. For example, `USERNAME-ci-test-app` where `USERNAME` is your {% data variables.product.company_short %} username. 1. Under "Homepage URL", enter a URL for your app. For example, you can use the URL of the repository that you created to store the code for your app. 1. Skip the "Identifying and authorizing users" and "Post installation" sections for this tutorial. 1. Make sure that **Active** is selected under "Webhooks". @@ -153,8 +152,9 @@ The following steps will guide you through configuring a {% data variables.produ 1. Under "Webhook secret", enter a random string. This secret is used to verify that webhooks are sent by {% data variables.product.prodname_dotcom %}. Save this string; you will use it later. 1. Under "Repository permissions", next to "Checks", select **Read & write**. 1. Under "Subscribe to events", select **Check suite** and **Check run**. -1. Under "Where can this GitHub App be installed?", select **Only on this account**. You can change this later if you want to publish your app. -1. Click **Create GitHub App**. +1. Under "Where can this {% data variables.product.prodname_github_app %} be installed?", select **Only on this account**. You can change this later if you want to publish your app.{% 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 %}**. ### Store your app's identifying information and credentials diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/quickstart.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/quickstart.md index 27aff14f9305..10742fc55623 100644 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/quickstart.md +++ b/content/apps/creating-github-apps/writing-code-for-a-github-app/quickstart.md @@ -45,11 +45,11 @@ In order to develop your app locally, you can use a webhook proxy URL to forward The following steps will guide you through configuring the app settings that are required for this quickstart. For more information about the settings, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)." -{% data reusables.apps.settings-step %} +{% data reusables.apps.settings-step-personal-orgs %} {% 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. For example, `USERNAME-quickstart-app` where `USERNAME` is your {% data variables.product.company_short %} username. +1. Click **New {% data variables.product.prodname_github_app %}**. +1. Under "{% data variables.product.prodname_github_app %} name", enter a name for your app. For example, `USERNAME-quickstart-app` where `USERNAME` is your {% data variables.product.company_short %} username. 1. Under "Homepage URL", enter `https://github.com/github/github-app-js-sample#readme`. 1. Skip the "Identifying and authorizing users" and "Post installation" sections for this quickstart. For more information about these settings, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)." 1. Make sure that **Active** is selected under "Webhooks." @@ -57,8 +57,8 @@ The following steps will guide you through configuring the app settings that are 1. Under "Webhook secret", enter a random string. You will use this string later. 1. Under "Repository permissions", next to "Pull requests," select **Read & write**. 1. Under "Subscribe to events", select **Pull request**. -1. Under "Where can this GitHub App be installed?", select **Only on this account**. -1. Click **Create GitHub App**. +1. Under "Where can this {% data variables.product.prodname_github_app %} be installed?", select **Only on this account**. +1. Click **Create {% data variables.product.prodname_github_app %}**. ## Step 4: Store identifying information and credentials diff --git a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/deleting-your-app-listing-from-github-marketplace.md b/content/apps/github-marketplace/listing-an-app-on-github-marketplace/deleting-your-app-listing-from-github-marketplace.md index 277ee8a06855..5e9a87a11782 100644 --- a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/deleting-your-app-listing-from-github-marketplace.md +++ b/content/apps/github-marketplace/listing-an-app-on-github-marketplace/deleting-your-app-listing-from-github-marketplace.md @@ -16,7 +16,7 @@ redirect_from: You can follow these steps to remove your app from {% data variables.product.prodname_marketplace %}. The listing will be removed from {% data variables.product.prodname_marketplace %} immediately. Existing subscriptions will be canceled at the end of the current billing cycle. Although the app will be removed from {% data variables.product.prodname_marketplace %}, you will not be able to delete your app until the current billing cycle ends. -{% data reusables.apps.settings-step %} +{% data reusables.apps.settings-step-personal-orgs %} {% data reusables.user-settings.developer_settings %} @@ -30,4 +30,4 @@ You can follow these steps to remove your app from {% data variables.product.pro ![Screenshot of the left sidebar on the app listing page. The overview option for the marketplace draft listing is outlined in dark orange.](/assets/images/marketplace/edit-marketplace-listing-overview.png) -1. Under "Remove your listing from GitHub Marketplace", click **Delist this Listing** +1. Under "Remove your listing from {% data variables.product.prodname_marketplace %}", click **Delist this Listing** diff --git a/content/apps/maintaining-github-apps/deleting-a-github-app.md b/content/apps/maintaining-github-apps/deleting-a-github-app.md index 1839c527dae7..a0bcd0a92abd 100644 --- a/content/apps/maintaining-github-apps/deleting-a-github-app.md +++ b/content/apps/maintaining-github-apps/deleting-a-github-app.md @@ -40,12 +40,11 @@ When you delete a {% data variables.product.prodname_github_app %} registration, ## Deleting 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. Select the GitHub App you want to delete. +{% data reusables.apps.enterprise-apps-steps %} +1. Select the {% data variables.product.prodname_github_app %} you want to delete. {% data reusables.user-settings.github_apps_advanced %} -1. Click **Delete GitHub App**. -1. In the confirmation box, type the name of the GitHub App to confirm you want to delete it. -1. Click **I understand the consequences, delete this GitHub App**. +1. Click **Delete {% data variables.product.prodname_github_app %}**. +1. In the confirmation box, type the name of the {% data variables.product.prodname_github_app %} to confirm you want to delete it. +1. Click **I understand the consequences, delete this {% data variables.product.prodname_github_app %}**. These steps only delete your {% data variables.product.prodname_github_app %} registration, and all of the organization and account installations it may have. They do not delete any code that you wrote for your app. However, any code that relies on your {% data variables.product.prodname_github_app %}'s credentials will no longer function. diff --git a/content/apps/maintaining-github-apps/managing-allowed-ip-addresses-for-a-github-app.md b/content/apps/maintaining-github-apps/managing-allowed-ip-addresses-for-a-github-app.md index c5dfa764e6eb..ff677db23ffb 100644 --- a/content/apps/maintaining-github-apps/managing-allowed-ip-addresses-for-a-github-app.md +++ b/content/apps/maintaining-github-apps/managing-allowed-ip-addresses-for-a-github-app.md @@ -32,10 +32,9 @@ or {% data reusables.identity-and-permissions.ip-address-add-or-remove-caching %} {% 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 %} {% data reusables.identity-and-permissions.ip-allow-lists-add-ip %} {% data reusables.identity-and-permissions.ip-allow-lists-add-description %} - The description is for your reference and is not used in the allow list of organizations where the {% data variables.product.prodname_github_app %} is installed. Instead, organization allow lists will include "Managed by the NAME GitHub App" as the description. + The description is for your reference and is not used in the allow list of organizations where the {% data variables.product.prodname_github_app %} is installed. Instead, organization allow lists will include "Managed by the NAME {% data variables.product.prodname_github_app %}" as the description. {% data reusables.identity-and-permissions.ip-allow-lists-add-entry %} diff --git a/content/apps/maintaining-github-apps/modifying-a-github-app-registration.md b/content/apps/maintaining-github-apps/modifying-a-github-app-registration.md index 3e3a19fad22d..32440568d2c5 100644 --- a/content/apps/maintaining-github-apps/modifying-a-github-app-registration.md +++ b/content/apps/maintaining-github-apps/modifying-a-github-app-registration.md @@ -27,7 +27,7 @@ You can modify your {% data variables.product.prodname_github_app %} registratio For example, you can change the name and description of your app, the permissions granted to your app, the webhooks your app subscribes to, or the visibility of your app. -You can also choose to test new optional features for your {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/activating-optional-features-for-github-apps)." +You can also choose to test new optional features for your {% data variables.product.prodname_github_app %}. See "[AUTOTITLE](/apps/maintaining-github-apps/activating-optional-features-for-github-apps)." @@ -37,8 +37,7 @@ You can also choose to test new optional features for your {% data variables.pro To modify a {% data variables.product.prodname_github_app %}, first navigate to the app settings page. {% 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 %} ## Changing the basic information of a {% data variables.product.prodname_github_app %} @@ -51,7 +50,7 @@ You can change the basic information of your {% data variables.product.prodname_ ## Requesting user authorization (OAuth) during installation -You can prompt users to authorize your {% data variables.product.prodname_github_app %} when they install it and generate a user access token. When you request user authorization (OAuth) during installation, you must also provide a callback URL where the user will be redirected after they authorize the installation. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)." +You can prompt users to authorize your {% data variables.product.prodname_github_app %} when they install it and generate a user access token. When you request user authorization (OAuth) during installation, you must also provide a callback URL where the user will be redirected after they authorize the installation. See "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)." {% data reusables.apps.navigate-to-app-settings-this-article %} 1. Under "Identifying and authorizing users," select or deselect **Request user authorization (OAuth) during installation**. @@ -66,9 +65,9 @@ You can use the device flow to authorize users for a headless app like a CLI too ## Adding or updating a setup URL -You can redirect people to a specific URL after they install your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)." +You can redirect people to a specific URL after they install your app. See "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)." -If you select **Request user authorization (OAuth) during installation**, you will not be able to enter a setup URL. Users will instead be redirected to the Callback URL as part of the authorization flow, where you can describe additional setup. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url)." +If you select **Request user authorization (OAuth) during installation**, you will not be able to enter a setup URL. Users will instead be redirected to the Callback URL as part of the authorization flow, where you can describe additional setup. See "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url)." {% data reusables.apps.navigate-to-app-settings-this-article %} 1. Under "Post installation," in the "Setup URL" field, enter the URL where you'd like to redirect users after they install your app. @@ -80,17 +79,17 @@ You can change the access permissions that are granted to your {% data variables When you change the **repository** or **organization** permissions of an app, each account where the app is installed will need to approve the new permissions. When you change the **account** permissions of an app, each user that has authorized the app will need to approve the permission changes. In both cases, {% data variables.product.prodname_dotcom %} will send an email to each organization owner or user, notifying them of the request to update the app's permissions. Updated permissions won't take effect on an installation or user authorization until the new permissions are approved. You can use the [installation webhook](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=new_permissions_accepted#installation) to find out when people accept new permissions for your app. -Changing the permissions of an app may also change the webhooks that your app can subscribe to and the actions that your app can take with the API. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)." +Changing the permissions of an app may also change the webhooks that your app can subscribe to and the actions that your app can take with the API. See "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)." {% data reusables.apps.navigate-to-app-settings-this-article %} 1. In the {% data variables.product.prodname_github_apps %} settings sidebar, click **Permissions & events**. -1. Under the sections "Repository permissions," "Organization permissions," and "Account permissions," modify the permissions you'd like to change. For each type of permission, select either "Read-only," "Read and write," or "No access" from the dropdown. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)." +1. Under the sections "Repository permissions," "Organization permissions," and "Account permissions," modify the permissions you'd like to change. For each type of permission, select either "Read-only," "Read and write," or "No access" from the dropdown. See "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)." 1. Optionally, under "Add a note to users," add a note telling your users why you are changing the permissions that your {% data variables.product.prodname_github_app %} requests. 1. Click **Save changes**. ## Activating or deactivating the {% data variables.product.prodname_github_app %} webhook -You can configure your {% data variables.product.prodname_github_app %} to receive webhooks for specific events on {% data variables.product.prodname_dotcom %} and automatically take action on them. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)." +You can configure your {% data variables.product.prodname_github_app %} to receive webhooks for specific events on {% data variables.product.prodname_dotcom %} and automatically take action on them. See "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)." {% data reusables.apps.navigate-to-app-settings-this-article %} 1. Under "Webhook," to enable or disable the webhook, select or deselect **Active**. @@ -101,18 +100,22 @@ You can configure your {% data variables.product.prodname_github_app %} to recei You can change the webhook events that a {% data variables.product.prodname_github_app %} subscribes to using the following steps. -{% data reusables.apps.webhooks-and-apps %} For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)." +{% data reusables.apps.webhooks-and-apps %} See "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)." {% data reusables.apps.navigate-to-app-settings-this-article %} -1. Activate the {% data variables.product.prodname_github_app %} webhook. For more information, see "[Activating or deactivating the {% data variables.product.prodname_github_app %} webhook](/apps/maintaining-github-apps/modifying-a-github-app#activating-or-deactivating-the-github-app-webhook)" in this article. +1. Activate the {% data variables.product.prodname_github_app %} webhook. See "[Activating or deactivating the {% data variables.product.prodname_github_app %} webhook](/apps/maintaining-github-apps/modifying-a-github-app#activating-or-deactivating-the-github-app-webhook)" in this article. 1. In the {% data variables.product.prodname_github_apps %} settings sidebar, click **Permissions & events**. -1. Under the sections "Repository permissions," "Organization permissions," and "Account permissions," select the permissions that are required for the events your app will subscribe to. For more information, see "[Changing the permissions of a {% data variables.product.prodname_github_app %}](#changing-the-permissions-of-a-github-app)." +1. Under the sections "Repository permissions," "Organization permissions," and "Account permissions," select the permissions that are required for the events your app will subscribe to. See "[Changing the permissions of a {% data variables.product.prodname_github_app %}](#changing-the-permissions-of-a-github-app)." 1. Under "Subscribe to Events," select the webhook events you would like your {% data variables.product.prodname_github_app %} to receive. 1. Click **Save changes**. ## Changing the visibility of a {% data variables.product.prodname_github_app %} -You can change the visibility settings of your {% data variables.product.prodname_github_app %} to control who can install it. Public apps cannot be made private if they're installed on other accounts. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private)." +You can change the visibility settings of your {% data variables.product.prodname_github_app %} to control who can install it. Public apps cannot be made private if they're installed on other accounts. See "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private)." + +{% ifversion enterprise-apps-public-beta %} +You can't change the visibility of an {% data variables.product.prodname_github_app %} owned by an enterprise. {% data variables.product.prodname_github_apps %} owned by an enterprise can only be installed on organizations within the enterprise. +{% endif %} {% data reusables.apps.navigate-to-app-settings-this-article %} {% data reusables.user-settings.github_apps_advanced %} diff --git a/content/apps/maintaining-github-apps/transferring-ownership-of-a-github-app.md b/content/apps/maintaining-github-apps/transferring-ownership-of-a-github-app.md index 7f308ea9b252..4ddf09aa9de5 100644 --- a/content/apps/maintaining-github-apps/transferring-ownership-of-a-github-app.md +++ b/content/apps/maintaining-github-apps/transferring-ownership-of-a-github-app.md @@ -21,14 +21,18 @@ The owner of a {% data variables.product.prodname_github_app %} registration can You can only transfer ownership to a user or organization. You cannot transfer ownership to a team. +{% ifversion enterprise-apps-public-beta %} +>[!NOTE] If your {% data variables.product.prodname_github_app %} is owned by an enterprise, you cannot transfer ownership. +{% endif %} + ## Transferring a {% data variables.product.prodname_github_app %} registration -{% data reusables.apps.settings-step %} +{% data reusables.apps.settings-step-personal-orgs %} {% data reusables.user-settings.developer_settings %} {% data reusables.user-settings.github_apps %} -1. Select the GitHub App whose ownership you want to transfer. +1. Select the {% data variables.product.prodname_github_app %} whose ownership you want to transfer. {% data reusables.user-settings.github_apps_advanced %} 1. Click **Transfer ownership**. -1. Under "Type the name of the GitHub App to confirm", type the name of the GitHub App you want to transfer. -1. Under "New owner's GitHub username or organization name", type the name of the user or organization you want to transfer the GitHub App to. -1. Click **Transfer this GitHub App**. +1. Under "Type the name of the {% data variables.product.prodname_github_app %} to confirm", type the name of the {% data variables.product.prodname_github_app %} you want to transfer. +1. Under "New owner's {% data variables.product.prodname_dotcom %} username or organization name", type the name of the user or organization you want to transfer the {% data variables.product.prodname_github_app %} to. +1. Click **Transfer this {% data variables.product.prodname_github_app %}**. diff --git a/content/apps/oauth-apps/maintaining-oauth-apps/activating-optional-features-for-oauth-apps.md b/content/apps/oauth-apps/maintaining-oauth-apps/activating-optional-features-for-oauth-apps.md index 6f46d4d42118..647fe4b09942 100644 --- a/content/apps/oauth-apps/maintaining-oauth-apps/activating-optional-features-for-oauth-apps.md +++ b/content/apps/oauth-apps/maintaining-oauth-apps/activating-optional-features-for-oauth-apps.md @@ -17,7 +17,7 @@ shortTitle: Activate optional features ## Activating optional features for {% data variables.product.prodname_oauth_apps %} -{% data reusables.apps.settings-step %} +{% data reusables.apps.settings-step-personal-orgs %} {% data reusables.user-settings.developer_settings %} {% data reusables.user-settings.oauth_apps %} 1. Select the {% data variables.product.prodname_oauth_app %} you want to enable an optional feature for. diff --git a/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md b/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md index 9ba7f59cabcb..9265fc8b395b 100644 --- a/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md +++ b/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md @@ -16,45 +16,45 @@ topics: - GitHub Apps shortTitle: App manifest --- -## About GitHub App Manifests +## About {% data variables.product.prodname_github_app %} Manifests -When someone registers a GitHub App from a manifest, they only need to follow a URL and name the app. The manifest includes the permissions, events, and webhook URL needed to automatically register the app. The manifest flow creates the GitHub App registration and generates the app's webhook secret, private key (PEM file), client secret, and GitHub App ID. The person who creates the {% data variables.product.prodname_github_app %} registration from the manifest will own the {% data variables.product.prodname_github_app %} registration and can choose to edit the registration's settings, delete it, or transfer it to another person on GitHub. +{% ifversion enterprise-apps-public-beta %} +>[!NOTE] {% data variables.product.prodname_github_app %} Manifests are not available for enterprise-owned {% data variables.product.prodname_github_apps %}. +{% endif %} -You can use [Probot](https://probot.github.io/) to get started with GitHub App Manifests or see an example implementation. See "[Using Probot to implement the GitHub App Manifest flow](#using-probot-to-implement-the-github-app-manifest-flow)" to learn more. +When someone registers a {% data variables.product.prodname_github_app %} from a manifest, they only need to follow a URL and name the app. The manifest includes the permissions, events, and webhook URL needed to automatically register the app. The manifest flow creates the {% data variables.product.prodname_github_app %} registration and generates the app's webhook secret, private key (PEM file), client secret, and {% data variables.product.prodname_github_app %} ID. The person who creates the {% data variables.product.prodname_github_app %} registration from the manifest will own the {% data variables.product.prodname_github_app %} registration and can choose to edit the registration's settings, delete it, or transfer it to another person on {% data variables.product.prodname_dotcom %}. -Here are some scenarios where you might use GitHub App Manifests to register pre-configured apps: +You can use [Probot](https://probot.github.io/) to get started with {% data variables.product.prodname_github_app %} Manifests or see an example implementation. See "[Using Probot to implement the {% data variables.product.prodname_github_app %} Manifest flow](#using-probot-to-implement-the-github-app-manifest-flow)" to learn more. -* Help new team members come up-to-speed quickly when developing GitHub Apps. -* Allow others to extend a GitHub App using the GitHub APIs without requiring them to configure an app. -* Create GitHub App reference designs to share with the GitHub community. -* Ensure you deploy GitHub Apps to development and production environments using the same configuration. -* Track revisions to a GitHub App configuration. +Here are some scenarios where you might use {% data variables.product.prodname_github_app %} Manifests to register pre-configured apps: -## Implementing the GitHub App Manifest flow +* Help new team members come up-to-speed quickly when developing {% data variables.product.prodname_github_apps %}. +* Allow others to extend a {% data variables.product.prodname_github_app %} using the {% data variables.product.prodname_dotcom %} APIs without requiring them to configure an app. +* Create {% data variables.product.prodname_github_app %} reference designs to share with the {% data variables.product.prodname_dotcom %} community. +* Ensure you deploy {% data variables.product.prodname_github_apps %} to development and production environments using the same configuration. +* Track revisions to a {% data variables.product.prodname_github_app %} configuration. -The GitHub App Manifest flow uses a handshaking process similar to the [OAuth flow](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). The flow uses a manifest to [register a GitHub App](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and receives a temporary `code` used to retrieve the app's private key, webhook secret, and ID. +## Implementing the {% data variables.product.prodname_github_app %} Manifest flow -{% note %} - -**Note:** You must complete all three steps in the GitHub App Manifest flow within one hour. +The {% data variables.product.prodname_github_app %} Manifest flow uses a handshaking process similar to the [OAuth flow](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). The flow uses a manifest to [register a {% data variables.product.prodname_github_app %}](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and receives a temporary `code` used to retrieve the app's private key, webhook secret, and ID. -{% endnote %} +>[!NOTE] You must complete all three steps in the {% data variables.product.prodname_github_app %} Manifest flow within one hour. -Follow these steps to implement the GitHub App Manifest flow: +Follow these steps to implement the {% data variables.product.prodname_github_app %} Manifest flow: -1. You redirect people to GitHub to register a new GitHub App. -1. GitHub redirects people back to your site. +1. You redirect people to {% data variables.product.prodname_dotcom %} to register a new {% data variables.product.prodname_github_app %}. +1. {% data variables.product.prodname_dotcom %} redirects people back to your site. 1. You exchange the temporary code to retrieve the app configuration. -### 1. You redirect people to GitHub to register a new GitHub App +### 1. You redirect people to {% data variables.product.prodname_dotcom %} to register a new {% data variables.product.prodname_github_app %} -To redirect people to register a new GitHub App, [provide a link](#examples) for them to click that sends a `POST` request to `https://github.com/settings/apps/new` for a personal account or `https://github.com/organizations/ORGANIZATION/settings/apps/new` for an organization account, replacing `ORGANIZATION` with the name of the organization account where the app will be registered. +To redirect people to register a new {% data variables.product.prodname_github_app %}, [provide a link](#examples) for them to click that sends a `POST` request to `https://github.com/settings/apps/new` for a personal account or `https://github.com/organizations/ORGANIZATION/settings/apps/new` for an organization account, replacing `ORGANIZATION` with the name of the organization account where the app will be registered. -You must include the [GitHub App Manifest parameters](#github-app-manifest-parameters) as a JSON-encoded string in a parameter called `manifest`. You can also include a `state` [parameter](#parameters) for additional security. +You must include the [{% data variables.product.prodname_github_app %} Manifest parameters](#github-app-manifest-parameters) as a JSON-encoded string in a parameter called `manifest`. You can also include a `state` [parameter](#parameters) for additional security. -The person registering the app will be redirected to a GitHub page with an input field where they can edit the name of the app you included in the `manifest` parameter. If you do not include a `name` in the `manifest`, they can set their own name for the app in this field. +The person registering the app will be redirected to a {% data variables.product.prodname_dotcom %} page with an input field where they can edit the name of the app you included in the `manifest` parameter. If you do not include a `name` in the `manifest`, they can set their own name for the app in this field. -#### GitHub App Manifest parameters +#### {% data variables.product.prodname_github_app %} Manifest parameters Name | Type | Description -----|------|------------- @@ -67,7 +67,7 @@ The person registering the app will be redirected to a GitHub page with an input `description` | `string` | A description of the {% data variables.product.prodname_github_app %}. `public` | `boolean` | Set to `true` when your {% data variables.product.prodname_github_app %} is available to the public or `false` when it is only accessible to the owner of the app. `default_events` | `array` | The list of [events](/webhooks-and-events/webhooks/webhook-events-and-payloads) the {% data variables.product.prodname_github_app %} subscribes to. -`default_permissions` | `object` | The set of permissions needed by the GitHub App. The format of the object uses the permission name for the key (for example, `issues`) and the access type for the value (for example, `write`). For more information, see "[AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)." +`default_permissions` | `object` | The set of permissions needed by the {% data variables.product.prodname_github_app %}. The format of the object uses the permission name for the key (for example, `issues`) and the access type for the value (for example, `write`). For more information, see "[AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)." `request_oauth_on_install` | `boolean` | Set to `true` to request the user to authorize the {% data variables.product.prodname_github_app %}, after the {% data variables.product.prodname_github_app %} is installed. `setup_on_update` | `boolean` | Set to `true` to redirect users to the `setup_url` after they update your {% data variables.product.prodname_github_app %} installation. @@ -156,9 +156,9 @@ This example uses a form on a web page with a button that triggers the `POST` re ``` -### 2. GitHub redirects people back to your site +### 2. {% data variables.product.prodname_dotcom %} redirects people back to your site -When the person clicks **Create GitHub App**, GitHub redirects back to the `redirect_url` with a temporary `code` in a code parameter. For example: +When the person clicks **Create {% data variables.product.prodname_github_app %}**, {% data variables.product.prodname_dotcom %} redirects back to the `redirect_url` with a temporary `code` in a code parameter. For example: https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679 @@ -168,9 +168,9 @@ If you provided a `state` parameter, you will also see that parameter in the `re ### 3. You exchange the temporary code to retrieve the app configuration -To complete the handshake, send the temporary `code` in a `POST` request to the [Create a GitHub App from a manifest](/rest/apps/apps#create-a-github-app-from-a-manifest) endpoint. The response will include the `id` (GitHub App ID), `pem` (private key), and `webhook_secret`. GitHub creates a webhook secret for the app automatically. You can store these values in environment variables on the app's server. For example, if your app uses [dotenv](https://github.com/bkeepers/dotenv) to store environment variables, you would store the variables in your app's `.env` file. +To complete the handshake, send the temporary `code` in a `POST` request to the [Create a {% data variables.product.prodname_github_app %} from a manifest](/rest/apps/apps#create-a-github-app-from-a-manifest) endpoint. The response will include the `id` ({% data variables.product.prodname_github_app %} ID), `pem` (private key), and `webhook_secret`. {% data variables.product.prodname_dotcom %} creates a webhook secret for the app automatically. You can store these values in environment variables on the app's server. For example, if your app uses [dotenv](https://github.com/bkeepers/dotenv) to store environment variables, you would store the variables in your app's `.env` file. -You must complete this step of the GitHub App Manifest flow within one hour. +You must complete this step of the {% data variables.product.prodname_github_app %} Manifest flow within one hour. {% note %} @@ -180,20 +180,20 @@ You must complete this step of the GitHub App Manifest flow within one hour. POST /app-manifests/{code}/conversions -For more information about the endpoint's response, see [Create a GitHub App from a manifest](/rest/apps/apps#create-a-github-app-from-a-manifest). +For more information about the endpoint's response, see [Create a {% data variables.product.prodname_github_app %} from a manifest](/rest/apps/apps#create-a-github-app-from-a-manifest). -When the final step in the manifest flow is completed, the person registering the app from the flow will be an owner of a registered GitHub App that they can install on any of their personal repositories. They can choose to extend the app using the GitHub APIs, transfer ownership to someone else, or delete it at any time. +When the final step in the manifest flow is completed, the person registering the app from the flow will be an owner of a registered {% data variables.product.prodname_github_app %} that they can install on any of their personal repositories. They can choose to extend the app using the {% data variables.product.prodname_dotcom %} APIs, transfer ownership to someone else, or delete it at any time. -## Using Probot to implement the GitHub App Manifest flow +## Using Probot to implement the {% data variables.product.prodname_github_app %} Manifest flow -[Probot](https://probot.github.io/) is a framework built with [Node.js](https://nodejs.org/) that performs many of the tasks needed by all GitHub Apps, like validating webhooks and performing authentication. Probot implements the [GitHub App manifest flow](#implementing-the-github-app-manifest-flow), making it easy to create and share GitHub App reference designs with the GitHub community. +[Probot](https://probot.github.io/) is a framework built with [Node.js](https://nodejs.org/) that performs many of the tasks needed by all {% data variables.product.prodname_github_apps %}, like validating webhooks and performing authentication. Probot implements the [{% data variables.product.prodname_github_app %} manifest flow](#implementing-the-github-app-manifest-flow), making it easy to create and share {% data variables.product.prodname_github_app %} reference designs with the {% data variables.product.prodname_dotcom %} community. To create a Probot App that you can share, follow these steps: -1. [Generate a new GitHub App](https://probot.github.io/docs/development/#generating-a-new-app). -1. Open the project you created, and customize the settings in the `app.yml` file. Probot uses the settings in `app.yml` as the [GitHub App Manifest parameters](#github-app-manifest-parameters). +1. [Generate a new {% data variables.product.prodname_github_app %}](https://probot.github.io/docs/development/#generating-a-new-app). +1. Open the project you created, and customize the settings in the `app.yml` file. Probot uses the settings in `app.yml` as the [{% data variables.product.prodname_github_app %} Manifest parameters](#github-app-manifest-parameters). 1. Add your application's custom code. -1. [Run the GitHub App locally](https://probot.github.io/docs/development/#running-the-app-locally) or [host it anywhere you'd like](#hosting-your-app-with-glitch). When you navigate to the hosted app's URL, you'll find a web page with a **Register GitHub App** button that people can click to register a preconfigured app. +1. [Run the {% data variables.product.prodname_github_app %} locally](https://probot.github.io/docs/development/#running-the-app-locally) or [host it anywhere you'd like](#hosting-your-app-with-glitch). When you navigate to the hosted app's URL, you'll find a web page with a **Register {% data variables.product.prodname_github_app %}** button that people can click to register a preconfigured app. Using [dotenv](https://github.com/bkeepers/dotenv), Probot creates a `.env` file and sets the `APP_ID`, `PRIVATE_KEY`, and `WEBHOOK_SECRET` environment variables with the values [retrieved from the app configuration](#3-you-exchange-the-temporary-code-to-retrieve-the-app-configuration). diff --git a/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md b/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md index 2064082b9b6b..05fdde2f96b7 100644 --- a/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md +++ b/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md @@ -29,7 +29,9 @@ Alternatively, you can create a {% data variables.product.prodname_github_app %} To create a custom configuration URL for a {% data variables.product.prodname_github_app %} on a personal or organization account, add query parameters after the following base URLs. * To register an app on a personal account, add URL parameters to: `{% data variables.product.oauth_host_code %}/settings/apps/new` -* To register an app on an organization account, add URL parameters to: `{% data variables.product.oauth_host_code %}/organizations/ORGANIZATION/settings/apps/new`. Replace `ORGANIZATION` with the name of the organization where you'd like the customer to register the app. +* To register an app on an organization account, add URL parameters to: `{% data variables.product.oauth_host_code %}/organizations/ORGANIZATION/settings/apps/new`. Replace `ORGANIZATION` with the name of the organization where you'd like the customer to register the app. {% ifversion enterprise-apps-public-beta %} + + >[!NOTE] The URL parameters for registering a {% data variables.product.prodname_github_app %} are also available for apps owned by enterprises. Since you can only install enterprise-owned apps on organizations within that enterprise, you can use the custom configuration URL for organizations.{% endif %} On the app registration page, the person registering the app can edit the preselected values before submitting the app. If you do not include parameters for required values (like `name`) in the URL query string, the person registering the app will need to input a value before they can register the app. @@ -45,14 +47,14 @@ You can use the following query parameters to select a specific configuration fo Parameter name | Type | Description -----|------|------------- -`name` | `string` | The name of the {% data variables.product.prodname_github_app %}. Give your app a clear and succinct name. Your app cannot have the same name as an existing GitHub user, unless it is your own user or organization name. A slugged version of your app's name will be shown in the user interface when your integration takes an action. +`name` | `string` | The name of the {% data variables.product.prodname_github_app %}. Give your app a clear and succinct name. Your app cannot have the same name as an existing {% data variables.product.prodname_dotcom %} user, unless it is your own user or organization name. A slugged version of your app's name will be shown in the user interface when your integration takes an action. `description` | `string` | A description of the {% data variables.product.prodname_github_app %}. `url` | `string` | The full URL of your {% data variables.product.prodname_github_app %}'s website homepage. `callback_urls` | `array of strings` | A full URL to redirect to after someone authorizes an installation. You can provide up to 10 callback URLs. These URLs are used if your app needs to generate a user access token. For example, `callback_urls[]=https://example.com&callback_urls[]=https://example-2.com`. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url)." `request_oauth_on_install` | `boolean` | If your app authorizes users using the OAuth flow, you can set this option to `true` to allow people to authorize the app when they install it, saving a step. If you select this option, the `setup_url` becomes unavailable and users will be redirected to your `callback_url` after installing the app. `setup_url` | `string` | The full URL to redirect to after someone installs the {% data variables.product.prodname_github_app %} if the app requires additional setup after installation. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url)." `setup_on_update` | `boolean` | Set to `true` to redirect people to the setup URL when installations have been updated, for example, after repositories are added or removed. -`public` | `boolean` | Set to `true` when your {% data variables.product.prodname_github_app %} is available to the public or `false` when it is only accessible to the owner of the app. +`public` | `boolean` | Set to `true` when your {% data variables.product.prodname_github_app %} is available to the public or `false` when it is only accessible to the owner of the app. This parameter does not apply to apps owned by enterprises. `webhook_active` | `boolean` | Set to `true` to enable webhook. Webhook is disabled by default. `webhook_url` | `string` | The full URL that you would like to send webhook event payloads to. `events` | `array of strings` | Webhook events. Some webhook events require `read` or `write` permissions for a resource before you can select the event when registering a new {% data variables.product.prodname_github_app %}. For more information, see the "[{% data variables.product.prodname_github_app %} webhook events](#github-app-webhook-events)" section. You can select multiple events in a query string. For example, `events[]=public&events[]=label`. diff --git a/content/apps/sharing-github-apps/sharing-your-github-app.md b/content/apps/sharing-github-apps/sharing-your-github-app.md index 69d9515d8782..bf6ab0ec6b60 100644 --- a/content/apps/sharing-github-apps/sharing-your-github-app.md +++ b/content/apps/sharing-github-apps/sharing-your-github-app.md @@ -27,20 +27,19 @@ For more information about how users can install your app from {% data variables {% ifversion fpt or ghec %} If your {% data variables.product.prodname_github_app %} is public, other users and organizations {% ifversion ghec %}within your enterprise {% endif %}can install your app. For more information about making your app public, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private)." -{% ifversion ghec %}If you are an {% data variables.product.prodname_emu %}, then you can only share your app with other users or organizations within your enterprise.{% endif %} +{% ifversion ghec %}If you are an {% data variables.product.prodname_emu %}, you can only share your app with users or organizations within your enterprise.{% endif %} {% else %} {% endif %} {% 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 share, click **Edit**. 1. Click **Public page**. {% data variables.product.company_short %} will bring you to the public page for your {% data variables.product.prodname_github_app %}. 1. Click **Install**. {% data variables.product.company_short %} will bring you to the installation URL for your {% data variables.product.prodname_github_app %}. The URL will look something like `{% data variables.product.oauth_host_code %}/{% ifversion ghes %}github-apps{% else %}apps{% endif %}/APP-NAME/installations/new`, where `APP-NAME` is the name of the {% data variables.product.prodname_github_app %}. 1. Share the installation URL with other users. For more information about how users can install your app from this URL, see "[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party)." - When you share the URL, you can include a `state` query parameter in the installation URL to preserve the state of the application page and return people back to that state after they install, authenticate, or accept updates to your GitHub App. For example, you could use the `state` to correlate an installation to a user or account. + When you share the URL, you can include a `state` query parameter in the installation URL to preserve the state of the application page and return people back to that state after they install, authenticate, or accept updates to your {% data variables.product.prodname_github_app %}. For example, you could use the `state` to correlate an installation to a user or account. To preserve a state, add it to the installation URL: `{% data variables.product.oauth_host_code %}/{% ifversion ghes %}github-apps{% else %}apps{% endif %}//installations/new?state=AB12t` diff --git a/content/apps/using-github-apps/authorizing-github-apps.md b/content/apps/using-github-apps/authorizing-github-apps.md index f4732f881efe..6e17b938d78a 100644 --- a/content/apps/using-github-apps/authorizing-github-apps.md +++ b/content/apps/using-github-apps/authorizing-github-apps.md @@ -17,7 +17,7 @@ redirect_from: ## About authorizing {% data variables.product.prodname_github_apps %} -Third-party applications that need to verify your {% data variables.product.company_short %} identity or interact with {% data variables.product.company_short %} on your behalf can ask you to authorize a {% data variables.product.prodname_github_app %} to do so. If a third-party application wants you to authorize a {% data variables.product.prodname_github_app %}, the application will bring you to a {% data variables.product.company_short %} page that prompts you to authorize the app. +Applications that are not owned by you, your organization, or {% data variables.product.prodname_marketplace %} may need to verify your {% data variables.product.github %} identity or interact with {% data variables.product.github %} on your behalf. These applications can request authorization for a {% data variables.product.prodname_github_app %} to perform these actions. If an application requests authorization, it will redirect you to a {% data variables.product.github %} page prompting you to authorize the app. When authorizing the {% data variables.product.prodname_github_app %}, you should ensure you trust the application owner and review the information that the application wants to access. During authorization, you'll be prompted to grant the {% data variables.product.prodname_github_app %} permission to do all of the following: diff --git a/content/apps/using-github-apps/installing-a-github-app-from-a-third-party.md b/content/apps/using-github-apps/installing-a-github-app-from-a-third-party.md index 108879259ec5..219f0660d954 100644 --- a/content/apps/using-github-apps/installing-a-github-app-from-a-third-party.md +++ b/content/apps/using-github-apps/installing-a-github-app-from-a-third-party.md @@ -8,9 +8,9 @@ versions: shortTitle: Install from third party --- -{% ifversion ghes %} +{% ifversion ghes < 3.16 %} -You cannot install third-party {% data variables.product.prodname_github_apps %} on organizations owned by your instance.{% ifversion ghes %} If you want to use the functionality of a third-party {% data variables.product.prodname_github_app %}, you can contact the app developer about making the {% data variables.product.prodname_github_app %} available for {% data variables.product.prodname_ghe_server %}. For more information, see "[AUTOTITLE](/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server)."{% endif %} +You cannot install third-party {% data variables.product.prodname_github_apps %} on organizations owned by your instance. If you want to use the functionality of a third-party {% data variables.product.prodname_github_app %}, you can contact the app developer about making the {% data variables.product.prodname_github_app %} available for {% data variables.product.prodname_ghe_server %}. For more information, see "[AUTOTITLE](/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server)." For more information about installing {% data variables.product.prodname_github_apps %} that you own, see "[AUTOTITLE](/apps/maintaining-github-apps/installing-your-own-github-app)." @@ -18,7 +18,13 @@ For more information about installing {% data variables.product.prodname_github_ ## About installing {% data variables.product.prodname_github_apps %} -This article describes how to install a {% data variables.product.prodname_github_app %} directly from the app owner instead of from {% data variables.product.prodname_marketplace %}. For more information on installing {% data variables.product.prodname_github_apps %} from {% data variables.product.prodname_marketplace %}, see "[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-in-your-personal-account)" and "[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-in-your-organization)." For more information about installing {% data variables.product.prodname_github_apps %} that you own, see "[AUTOTITLE](/apps/maintaining-github-apps/installing-your-own-github-app)." +{% ifversion fpt or ghec %} + +This article describes how to install a {% data variables.product.prodname_github_app %} directly from the app owner instead of from {% data variables.product.prodname_marketplace %}. For more information on installing {% data variables.product.prodname_github_apps %} from {% data variables.product.prodname_marketplace %}, see "[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-in-your-personal-account)" and "[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-in-your-organization)." For more information about installing {% data variables.product.prodname_github_apps %} that you own, see "[AUTOTITLE](/apps/maintaining-github-apps/installing-your-own-github-app)."{% endif %} + +{% ifversion enterprise-apps-public-beta %} +>[!NOTE] This installation flow applies to any {% data variables.product.prodname_github_app %}, whether it’s a third-party app or an app owned by your enterprise. You can install the app manually using the link provided by the app owner. +{% endif %} {% data reusables.apps.about-installation %} @@ -40,7 +46,7 @@ Admins of repositories that are owned by an organization can also install {% dat Organization members who are not organization owners or repository admins can still select the organization during the install process. Instead of installing the app, {% data variables.product.company_short %} will send a notification to the organization owner to request the organization owner to install the app. -The "app manager" role in an organization does not give a person the ability to install a {% data variables.product.prodname_github_app %} in the organization. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers)." +The "app manager" role in an organization does not give a person the ability to install a {% data variables.product.prodname_github_app %} in the organization. See "[AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers)." ## Installing a {% data variables.product.prodname_github_app %} diff --git a/content/apps/using-github-apps/installing-your-own-github-app.md b/content/apps/using-github-apps/installing-your-own-github-app.md index 8c9c1e1b9ea9..69d56cd9660a 100644 --- a/content/apps/using-github-apps/installing-your-own-github-app.md +++ b/content/apps/using-github-apps/installing-your-own-github-app.md @@ -18,17 +18,17 @@ shortTitle: Install your own app ## About installing your own {% data variables.product.prodname_github_app %} -Once you create a {% data variables.product.prodname_github_app %}, you can install it. If your {% data variables.product.prodname_github_app %} is owned by a personal account{% ifversion ghec%} and you are not an {% data variables.product.prodname_emu %}{% endif %}, you can install it on your account. If your {% data variables.product.prodname_github_app %} is owned by an organization and you are an organization owner, you can install it on the organization. +After creating a {% data variables.product.prodname_github_app %}, you can install it based on its visibility. -{% ifversion fpt or ghec %} -If your {% data variables.product.prodname_github_app %} is public{% ifversion ghec%} and you are not an {% data variables.product.prodname_emu %}{% endif %}, you can also share your {% data variables.product.prodname_github_app %} with other users or organizations. {% ifversion ghec%}If you are an {% data variables.product.prodname_emu %}, then you can only share your app with other organizations within your enterprise.{% endif %}For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/sharing-your-github-app)." -{% else %} -If your {% data variables.product.prodname_github_app %} is public, you can also share your {% data variables.product.prodname_github_app %} with other users or organizations within your enterprise. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/sharing-your-github-app)." -{% endif %} +* **Only on this account**: The {% data variables.product.prodname_github_app %} can only be installed on the organization or user account that created it.{% ifversion ghec %} If you are an {% data variables.product.prodname_emu %}, this option is not available for apps you create.{% ifversion enterprise-apps-public-beta %} This visibility is not available for apps registered by an enterprise.{% endif %}{% endif %} +* **Any account**: You can install this {% data variables.product.prodname_github_app %} on your user account or any organization account where you are an organization owner.{% ifversion enterprise-apps-public-beta %} This visibility is not available for apps registered by an enterprise. +* **Only enterprise organizations**: If the {% data variables.product.prodname_github_app %} is owned by an enterprise, you can only install the app on organizations within the enterprise. Organizations where you are an organization owner will appear in the installation options.{% endif %}{% ifversion ghec %} + +If you are an {% data variables.product.prodname_emu %}, you cannot install a {% data variables.product.prodname_github_app %} on your user account.{% endif %} ## Installing your own {% data variables.product.prodname_github_app %} -{% data reusables.apps.settings-step %} +{% data reusables.apps.settings-step-personal-orgs %} {% data reusables.user-settings.developer_settings %} {% data reusables.user-settings.github_apps %} 1. Next to the {% data variables.product.prodname_github_app %} that you want to install, click **Edit**. diff --git a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent.md b/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent.md index 7cb0e7b9d1e9..064465349e3e 100644 --- a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent.md +++ b/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent.md @@ -21,8 +21,7 @@ Once you have configured your server and created your {% data variables.product. ## Configuring your {% data variables.product.prodname_github_app %} {% data reusables.apps.settings-step %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} +{% data reusables.apps.enterprise-apps-steps %} 1. To the right of the {% data variables.product.prodname_github_app %} you want to configure for your {% data variables.product.prodname_copilot_extension_short %}, click **Edit**. 1. In the "Identifying and authorizing users" section, under "Callback URL", enter your server's hostname, then click **Save changes**. diff --git a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension.md b/content/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension.md index 50495c6c4273..70f91a7754c4 100644 --- a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension.md +++ b/content/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension.md @@ -21,8 +21,7 @@ A {% data variables.product.prodname_copilot_extension_short %} is a {% data var ## Creating a {% data variables.product.prodname_github_app %} {% data reusables.apps.settings-step %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} +{% 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. diff --git a/content/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks.md b/content/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks.md index 0eff4b08260a..07d9e2cdc660 100644 --- a/content/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks.md +++ b/content/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks.md @@ -49,8 +49,7 @@ The owner of a {% data variables.product.prodname_github_app %} can redeliver we You can use the {% data variables.product.company_short %} web interface or the REST API to redeliver webhooks for a {% data variables.product.prodname_github_app %}. For more information about using the REST API redeliver, see "[AUTOTITLE](/rest/apps/webhooks)." {% 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 redeliver a webhook for, click **Edit**. 1. In the sidebar, click **Advanced**. {% data reusables.webhooks.webhook_recent_deliveries_redeliver %} diff --git a/content/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries.md b/content/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries.md index 8a5c8e100dc4..02461e1c0b87 100644 --- a/content/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries.md +++ b/content/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries.md @@ -16,9 +16,9 @@ You can view details about webhook deliveries that occurred in the past {% data For each webhook delivery, you can view: -* the request headers and payload that {% data variables.product.company_short %} sent -* the time at which the request was sent -* the response that {% data variables.product.company_short %} received from your server +* The request headers and payload that {% data variables.product.company_short %} sent +* The time at which the request was sent +* The response that {% data variables.product.company_short %} received from your server You can also redeliver recent webhook deliveries. For more information, see "[AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks)." @@ -55,8 +55,7 @@ The owner of a {% data variables.product.prodname_github_app %} can view recent You can use the {% data variables.product.company_short %} web interface or the REST API to view recent webhook deliveries for a {% data variables.product.prodname_github_app %}. For more information about using the REST API to view recent deliveries, see "[AUTOTITLE](/rest/apps/webhooks)." {% 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 view webhook deliveries for, click **Edit**. 1. In the sidebar, click **Advanced**. {% data reusables.webhooks.webhook_recent_deliveries %} diff --git a/content/webhooks/using-webhooks/creating-webhooks.md b/content/webhooks/using-webhooks/creating-webhooks.md index a2de9afc976e..d04ab1934567 100644 --- a/content/webhooks/using-webhooks/creating-webhooks.md +++ b/content/webhooks/using-webhooks/creating-webhooks.md @@ -139,8 +139,7 @@ For more information about configuring a webhook when you register a {% data var To configure a webhook for an existing {% data variables.product.prodname_github_app %} registration: {% 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 configure the webhook for, click **Edit**. 1. Under "Webhook," select **Active**. 1. Under "Webhook URL", type the URL where you'd like to receive payloads. diff --git a/content/webhooks/using-webhooks/disabling-webhooks.md b/content/webhooks/using-webhooks/disabling-webhooks.md index 9c95d5736fdb..270680c279d3 100644 --- a/content/webhooks/using-webhooks/disabling-webhooks.md +++ b/content/webhooks/using-webhooks/disabling-webhooks.md @@ -92,8 +92,7 @@ You can disable webhooks that were previously enabled for events relating to {% Each {% data variables.product.prodname_github_app %} has one webhook. You cannot delete the webhook, but you can deactivate the webhook. The owner of a {% data variables.product.prodname_github_app %} can deactivate the webhook the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also deactivate the webhook for the app. {% 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 deactivate the webhook for, click **Edit**. 1. Under "Webhook," deselect **Active** to disable the webhook. 1. Click **Save changes**. diff --git a/data/features/enterprise-apps-public-beta.yml b/data/features/enterprise-apps-public-beta.yml new file mode 100644 index 000000000000..ba0d825288a5 --- /dev/null +++ b/data/features/enterprise-apps-public-beta.yml @@ -0,0 +1,6 @@ +# Reference: #15531 +# Documentation for enterprise-owned GitHub Apps + +versions: + ghec: '*' + ghes: '>=3.16' diff --git a/data/reusables/apps/enterprise-apps-beta.md b/data/reusables/apps/enterprise-apps-beta.md new file mode 100644 index 000000000000..62f4c58856d4 --- /dev/null +++ b/data/reusables/apps/enterprise-apps-beta.md @@ -0,0 +1 @@ +>[!NOTE] Enterprise-owned {% data variables.product.prodname_github_apps %} are currently in {% data variables.release-phases.public_preview %} and subject to change. diff --git a/data/reusables/apps/enterprise-apps-steps.md b/data/reusables/apps/enterprise-apps-steps.md new file mode 100644 index 000000000000..7746ca61aeda --- /dev/null +++ b/data/reusables/apps/enterprise-apps-steps.md @@ -0,0 +1,8 @@ +{% ifversion enterprise-apps-public-beta %} +1. Navigate to the {% data variables.product.prodname_github_app %} settings. + * For an app owned by a personal account or organization: + 1. In the left sidebar, click **{% octicon "code" aria-hidden="true" %} Developer settings**, then click **{% data variables.product.prodname_github_apps %}**. + * For an app owned by an enterprise: + 1. In the left sidebar, {% ifversion ghec %}under "Settings",{% elsif ghes %} click **Settings**, then{% endif %} click **{% data variables.product.prodname_github_apps %}**.{% else %} +{% data reusables.user-settings.developer_settings %} +{% data reusables.user-settings.github_apps %}{% endif %} diff --git a/data/reusables/apps/settings-step-personal-orgs.md b/data/reusables/apps/settings-step-personal-orgs.md new file mode 100644 index 000000000000..d6c42a7720c0 --- /dev/null +++ b/data/reusables/apps/settings-step-personal-orgs.md @@ -0,0 +1,6 @@ +1. In the upper-right corner of any page on {% data variables.product.prodname_dotcom %}, click your profile photo. +1. Navigate to your account settings. + * For an app owned by a personal account, click **Settings**. + * For an app owned by an organization: + 1. Click **Your organizations**. + 1. To the right of the organization, click **Settings**. diff --git a/data/reusables/apps/settings-step.md b/data/reusables/apps/settings-step.md index d6c42a7720c0..87edf7638c53 100644 --- a/data/reusables/apps/settings-step.md +++ b/data/reusables/apps/settings-step.md @@ -3,4 +3,9 @@ * For an app owned by a personal account, click **Settings**. * For an app owned by an organization: 1. Click **Your organizations**. - 1. To the right of the organization, click **Settings**. + 1. To the right of the organization, click **Settings**.{% ifversion enterprise-apps-public-beta %} + * For an app owned by an enterprise:{% ifversion ghec %} + 1. If you use {% data variables.product.prodname_emus %}, click **Your enterprise** to go directly to the enterprise account settings. + 1. If you use personal accounts, click **Your enterprises** and then to the right of the enterprise, click **Settings**.{% elsif ghes %} + 1. Click **Enterprise settings**. +{% endif %}{% endif %}