diff --git a/assets/images/github-apps/authorize_app.png b/assets/images/github-apps/authorize_app.png new file mode 100644 index 000000000000..d25cf67a1d10 Binary files /dev/null and b/assets/images/github-apps/authorize_app.png differ diff --git a/assets/images/github-apps/install_app.png b/assets/images/github-apps/install_app.png new file mode 100644 index 000000000000..2170708b4577 Binary files /dev/null and b/assets/images/github-apps/install_app.png differ diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md index 817c3b1ca6ca..4fbca81e3cf8 100644 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md +++ b/content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md @@ -8,7 +8,7 @@ versions: ghec: '*' topics: - GitHub Apps -shortTitle: Authentication overview +shortTitle: About authentication redirect_from: - /apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps - /apps/building-github-apps/authentication-options-for-github-apps diff --git a/content/apps/creating-github-apps/guides/index.md b/content/apps/creating-github-apps/guides/index.md index 3e65b4cad572..0fd0417bf669 100644 --- a/content/apps/creating-github-apps/guides/index.md +++ b/content/apps/creating-github-apps/guides/index.md @@ -13,12 +13,12 @@ topics: - GitHub Apps children: - /quickstart - - /setting-up-your-development-environment-to-create-a-github-app - /building-a-github-app-that-responds-to-webhook-events - /building-a-login-with-github-button-with-a-github-app - /building-a-cli-with-a-github-app - - /using-the-github-api-in-your-app - /making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow + - /setting-up-your-development-environment-to-create-a-github-app + - /using-the-github-api-in-your-app - /creating-ci-tests-with-the-checks-api - - /migrating-oauth-apps-to-github-apps --- + diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps.md b/content/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps.md index 3412e22afe61..c54a67aa2675 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps.md @@ -53,6 +53,10 @@ When building an integration, you should consider using a {% data variables.prod In general, {% data variables.product.prodname_github_app %}s are preferred over {% data variables.product.prodname_oauth_app %}s. +Both {% data variables.product.prodname_oauth_app %}s and {% data variables.product.prodname_github_app %}s use OAuth 2.0. + +{% data variables.product.prodname_oauth_app %}s can only act on behalf of a user while {% data variables.product.prodname_github_app %}s can either act on behalf of a user or independently of a user. + For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)." For information on how to migrate an existing {% data variables.product.prodname_oauth_app %} to a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps)." diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url.md b/content/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url.md index cae8908c9a66..cc4057c13dde 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url.md @@ -15,7 +15,7 @@ redirect_from: When you create a {% data variables.product.prodname_github_app %}, you can specify a callback URL. When you use the web application flow to generate a user access token in order to act on behalf of a user, users will be redirected to the callback URL after they authorize the app. -You can specify up to 10 callback URLs. If you specify multiple callback URLs, you can use the `redirect_uri` parameter when you prompt the user to authorize your app, to indicate which callback URL the user should be redirected to. If you do not specify `redirect_uri`, the first callback URL will be used. +You can specify up to 10 callback URLs. If you specify multiple callback URLs, you can use the `redirect_uri` parameter when you prompt the user to authorize your app, to indicate which callback URL the user should be redirected to. If you do not specify `redirect_uri`, the first callback URL will be used. For more information about using the `redirect_uri` parameter, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)". The callback URL is different from the setup URL. Users are redirected to the setup URL after they install an app. Users are redirected to the callback URL when they authorize an app via the web application flow. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url)." diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app.md b/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app.md index 4e351ade677f..af4bbec8d229 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app.md @@ -1,5 +1,6 @@ --- title: Creating a GitHub App +shortTitle: Create a {% data variables.product.prodname_github_app %} intro: 'You can create a {% data variables.product.prodname_github_app %} under your personal account or under any organization you own.' redirect_from: - /early-access/integrations/creating-an-integration diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/index.md b/content/apps/creating-github-apps/setting-up-a-github-app/index.md index 4522ae63015e..2baf69fbba87 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/index.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/index.md @@ -13,17 +13,15 @@ topics: - GitHub Apps children: - /about-creating-github-apps - - /rate-limits-for-github-apps + - /migrating-oauth-apps-to-github-apps + - /best-practices-for-creating-a-github-app - /creating-a-github-app + - /about-the-user-authorization-callback-url + - /about-the-setup-url - /choosing-permissions-for-a-github-app - /using-webhooks-with-github-apps - /making-a-github-app-public-or-private - - /making-your-github-app-available-for-github-enterprise-server - - /creating-a-github-app-from-a-manifest - - /creating-a-github-app-using-url-parameters + - /rate-limits-for-github-apps - /creating-a-custom-badge-for-your-github-app - - /about-the-user-authorization-callback-url - - /about-the-setup-url - - /best-practices-for-creating-a-github-app --- diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private.md b/content/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private.md index c7c95be202f1..0c7bdc1076c8 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private.md @@ -17,7 +17,7 @@ versions: ghec: '*' topics: - GitHub Apps -shortTitle: Manage app visibility +shortTitle: Visibility --- ## About visibility for {% data variables.product.prodname_github_app %}s diff --git a/content/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps.md b/content/apps/creating-github-apps/setting-up-a-github-app/migrating-oauth-apps-to-github-apps.md similarity index 99% rename from content/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps.md rename to content/apps/creating-github-apps/setting-up-a-github-app/migrating-oauth-apps-to-github-apps.md index da818a0e65fb..c1eb1dfb906e 100644 --- a/content/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/migrating-oauth-apps-to-github-apps.md @@ -5,6 +5,7 @@ redirect_from: - /apps/migrating-oauth-apps-to-github-apps - /developers/apps/migrating-oauth-apps-to-github-apps - /developers/apps/getting-started-with-apps/migrating-oauth-apps-to-github-apps + - /apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps versions: fpt: '*' ghes: '*' @@ -12,7 +13,7 @@ versions: ghec: '*' topics: - GitHub Apps -shortTitle: Migrate from {% data variables.product.prodname_oauth_app %}s +shortTitle: 'Migrate from {% data variables.product.prodname_oauth_app %}s' --- ## Benefits of migrating from {% data variables.product.prodname_oauth_app %}s to {% data variables.product.prodname_github_app %}s diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps.md b/content/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps.md index 578d5e722558..2b38b7734f58 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps.md @@ -1,6 +1,6 @@ --- title: Using webhooks with GitHub Apps -shortTitle: Using webhooks +shortTitle: Webhooks intro: 'Your {% data variables.product.prodname_github_app %} can subscribe to webhook events to receive notifications whenever certain activity occurs.' versions: fpt: '*' diff --git a/content/apps/index.md b/content/apps/index.md index f9cb799dab9f..acd38a9c7c8d 100644 --- a/content/apps/index.md +++ b/content/apps/index.md @@ -4,20 +4,26 @@ shortTitle: Apps intro: 'Go deeper with {% data variables.product.prodname_dotcom %} by integrating with our APIs and webhooks, customizing your {% data variables.product.prodname_dotcom %} workflow, and building and sharing apps with the community.' introLinks: overview: /apps/overview + quickstart: /apps/creating-github-apps/guides/quickstart layout: product-landing featuredLinks: startHere: - - /apps/creating-github-apps/setting-up-a-github-app/about-apps + - /apps/using-github-apps/about-using-github-apps + - /apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps - /apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps - - /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app - /apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app popular: - /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app - - /apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app - - /apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace + - /apps/using-github-apps/authorizing-github-apps + - /apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events + - /apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app + - /apps/creating-github-apps/guides/building-a-cli-with-a-github-app + - /apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow guideCards: - - /apps/creating-github-apps/guides/creating-ci-tests-with-the-checks-api - - /apps/creating-github-apps/guides/using-the-github-api-in-your-app + - /apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events + - /apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app + - /apps/creating-github-apps/guides/building-a-cli-with-a-github-app + - /apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow changelog: label: apps versions: @@ -31,6 +37,7 @@ children: - /overview - /using-github-apps - /creating-github-apps + - /sharing-github-apps - /maintaining-github-apps - /publishing-apps-to-github-marketplace - /oauth-apps 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 13ed652d8912..70f1ac262837 100644 --- a/content/apps/maintaining-github-apps/deleting-a-github-app.md +++ b/content/apps/maintaining-github-apps/deleting-a-github-app.md @@ -1,5 +1,6 @@ --- title: Deleting a GitHub App +shortTitle: Delete your app intro: 'You can delete {% data variables.product.prodname_github_app %}s that you own if you no longer want to use or maintain the app.' redirect_from: - /apps/building-integrations/managing-github-apps/deleting-a-github-app diff --git a/content/apps/maintaining-github-apps/index.md b/content/apps/maintaining-github-apps/index.md index 28daaf2504ab..12d5fa609cbc 100644 --- a/content/apps/maintaining-github-apps/index.md +++ b/content/apps/maintaining-github-apps/index.md @@ -13,12 +13,10 @@ versions: topics: - GitHub Apps children: - - /about-github-app-managers - /modifying-a-github-app - - /managing-allowed-ip-addresses-for-a-github-app - - /installing-your-own-github-app - - /sharing-your-github-app - /activating-optional-features-for-github-apps + - /about-github-app-managers + - /managing-allowed-ip-addresses-for-a-github-app - /suspending-a-github-app-installation - /transferring-ownership-of-a-github-app - /deleting-a-github-app diff --git a/content/apps/maintaining-github-apps/modifying-a-github-app.md b/content/apps/maintaining-github-apps/modifying-a-github-app.md index 0ea2d9725fe9..a5d2fa148e10 100644 --- a/content/apps/maintaining-github-apps/modifying-a-github-app.md +++ b/content/apps/maintaining-github-apps/modifying-a-github-app.md @@ -1,5 +1,6 @@ --- title: Modifying a GitHub App +shortTitle: Modify app settings intro: '{% data reusables.shortdesc.modifying_github_apps %}' redirect_from: - /apps/building-integrations/managing-github-apps/modifying-a-github-app diff --git a/content/apps/maintaining-github-apps/suspending-a-github-app-installation.md b/content/apps/maintaining-github-apps/suspending-a-github-app-installation.md index 5ddedc7a064a..57b9b426a45e 100644 --- a/content/apps/maintaining-github-apps/suspending-a-github-app-installation.md +++ b/content/apps/maintaining-github-apps/suspending-a-github-app-installation.md @@ -12,7 +12,7 @@ versions: ghec: '*' topics: - GitHub Apps -shortTitle: Suspend app installation +shortTitle: Suspend an installation --- When a {% data variables.product.prodname_github_app %} is suspended for an installation, the {% data variables.product.prodname_github_app %} cannot access resources owned by that installation account. For example, you might want to suspend your {% data variables.product.prodname_github_app %} if you are worried that your app's credentials were leaked. diff --git a/content/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app.md b/content/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app.md index f3993f982229..c6b3d0ba7865 100644 --- a/content/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app.md +++ b/content/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app.md @@ -1,6 +1,6 @@ --- title: Authenticating to the REST API with an OAuth App -shortTitle: Authenticating with OAuth App +shortTitle: Authenticate with an OAuth App intro: Learn about the different ways to authenticate with some examples. redirect_from: - /guides/basics-of-authentication diff --git a/content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md b/content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md index 03f330726fa8..a441b07be9cf 100644 --- a/content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md +++ b/content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md @@ -21,7 +21,11 @@ topics: {% note %} -**Note**: Consider building a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %}. {% data variables.product.prodname_github_app %}s can act on behalf of a user, similar to an {% data variables.product.prodname_oauth_app %}, or as themselves, which is beneficial for automations that do not require user input. Additionally, {% data variables.product.prodname_github_app %}s use fine grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps)." +**Note**: Consider building a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %}. + +Both {% data variables.product.prodname_oauth_app %}s and {% data variables.product.prodname_github_app %}s use OAuth 2.0. + +{% data variables.product.prodname_github_app %}s can act on behalf of a user, similar to an {% data variables.product.prodname_oauth_app %}, or as themselves, which is beneficial for automations that do not require user input. Additionally, {% data variables.product.prodname_github_app %}s use fine grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps)." {% endnote %} diff --git a/content/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app.md b/content/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app.md index e1e53c6860a6..7f393d860d66 100644 --- a/content/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app.md +++ b/content/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app.md @@ -17,7 +17,15 @@ topics: {% note %} -**Note**: Consider building a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %}. {% data variables.product.prodname_github_app %}s use fine-grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps)." +**Note**: Consider building a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %}. + +Both {% data variables.product.prodname_oauth_app %}s and {% data variables.product.prodname_github_app %}s use OAuth 2.0. + +{% data variables.product.prodname_oauth_app %}s can only act on behalf of a user while {% data variables.product.prodname_github_app %}s can either act on behalf of a user or independently of a user. + +{% data variables.product.prodname_github_app %}s use fine-grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. + +For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps)." {% endnote %} diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest.md b/content/apps/sharing-github-apps/creating-a-github-app-from-a-manifest.md similarity index 99% rename from content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest.md rename to content/apps/sharing-github-apps/creating-a-github-app-from-a-manifest.md index 313711c7ba28..5b5642dd6d66 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest.md +++ b/content/apps/sharing-github-apps/creating-a-github-app-from-a-manifest.md @@ -6,6 +6,7 @@ redirect_from: - /developers/apps/creating-a-github-app-from-a-manifest - /developers/apps/building-github-apps/creating-a-github-app-from-a-manifest - /apps/creating-github-apps/creating-github-apps/creating-a-github-app-from-a-manifest + - /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest versions: fpt: '*' ghes: '*' diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters.md b/content/apps/sharing-github-apps/creating-a-github-app-using-url-parameters.md similarity index 99% rename from content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters.md rename to content/apps/sharing-github-apps/creating-a-github-app-using-url-parameters.md index 02d00411d4ca..8c0a2a47500d 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters.md +++ b/content/apps/sharing-github-apps/creating-a-github-app-using-url-parameters.md @@ -6,6 +6,7 @@ redirect_from: - /developers/apps/creating-a-github-app-using-url-parameters - /developers/apps/building-github-apps/creating-a-github-app-using-url-parameters - /apps/creating-github-apps/creating-github-apps/creating-a-github-app-using-url-parameters + - /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters versions: fpt: '*' ghes: '*' diff --git a/content/apps/sharing-github-apps/index.md b/content/apps/sharing-github-apps/index.md new file mode 100644 index 000000000000..e4f1d1f1e7be --- /dev/null +++ b/content/apps/sharing-github-apps/index.md @@ -0,0 +1,17 @@ +--- +title: 'Sharing {% data variables.product.prodname_github_apps %}' +intro: 'After you create a public {% data variables.product.prodname_github_app %}, you can share your {% data variables.product.prodname_github_app %} with other {% data variables.product.company_short %} users.' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - GitHub Apps +children: + - /sharing-your-github-app + - /making-your-github-app-available-for-github-enterprise-server + - /creating-a-github-app-from-a-manifest + - /creating-a-github-app-using-url-parameters +--- + diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/making-your-github-app-available-for-github-enterprise-server.md b/content/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server.md similarity index 86% rename from content/apps/creating-github-apps/setting-up-a-github-app/making-your-github-app-available-for-github-enterprise-server.md rename to content/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server.md index 4d5497d34745..b751274f9b3e 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/making-your-github-app-available-for-github-enterprise-server.md +++ b/content/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server.md @@ -9,13 +9,19 @@ versions: ghec: '*' topics: - GitHub Apps +redirect_from: + - /apps/creating-github-apps/setting-up-a-github-app/making-your-github-app-available-for-github-enterprise-server --- ## About developing {% data variables.product.prodname_github_app %}s for {% data variables.product.prodname_ghe_server %} If you want your {% data variables.product.prodname_github_app %} to be available to organizations in a {% data variables.product.prodname_ghe_server %} instance that you are not part of, you must take the following steps. -These steps are not required if your {% data variables.product.prodname_github_app %} will only be used by organizations in a {% data variables.product.prodname_ghe_server %} instance that you are part of. +{% ifversion ghes %} +These steps are not required if your {% data variables.product.prodname_github_app %} will only be used by organizations in a {% data variables.product.prodname_ghe_server %} instance that you are part of. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/installing-your-own-github-app)." +{% endif %} + +If {% data variables.product.prodname_ghe_server %} access is important, consider whether a custom action for {% data variables.product.prodname_actions %} will suit your needs instead. Public actions are available on {% data variables.product.prodname_ghe_server %} instances with {% data variables.product.prodname_github_connect %}. For more information, see {% ifversion ghes %}"[AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect)."{% else %}"[AUTOTITLE](/enterprise-server@latest/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect)" in the {% data variables.product.prodname_ghe_server %} documentation.{% endif %} ## Each {% data variables.product.prodname_ghe_server %} instance must create their own {% data variables.product.prodname_github_app %} diff --git a/content/apps/maintaining-github-apps/sharing-your-github-app.md b/content/apps/sharing-github-apps/sharing-your-github-app.md similarity index 80% rename from content/apps/maintaining-github-apps/sharing-your-github-app.md rename to content/apps/sharing-github-apps/sharing-your-github-app.md index 907ace5c4dd5..0ba90e883099 100644 --- a/content/apps/maintaining-github-apps/sharing-your-github-app.md +++ b/content/apps/sharing-github-apps/sharing-your-github-app.md @@ -7,11 +7,13 @@ versions: ghae: '*' ghes: '*' shortTitle: Share your app +redirect_from: + - /apps/maintaining-github-apps/sharing-your-github-app --- {% ifversion fpt or ghec %} -### Sharing your {% data variables.product.prodname_github_app %} on {% data variables.product.prodname_marketplace %} +## Sharing your {% data variables.product.prodname_github_app %} on {% data variables.product.prodname_marketplace %} If your {% data variables.product.prodname_github_app %} is public, you can choose to publish it to {% data variables.product.prodname_marketplace %}. For more information, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace)." @@ -21,7 +23,7 @@ For more information about how users can install your app from {% data variables {% endif %} -### Sharing your {% data variables.product.prodname_github_app %} via an install link +## Sharing your {% data variables.product.prodname_github_app %} via an install link {% ifversion fpt or ghec %} If your {% data variables.product.prodname_github_app %} is public, other users and organizations {% ifversion ghae or 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)." @@ -42,3 +44,7 @@ If your {% data variables.product.prodname_github_app %} is public, other users 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. To preserve a state, add it to the installation URL: `{% data variables.product.oauth_host_code %}/{% ifversion ghes or ghae %}github-apps{% else %}apps{% endif %}//installations/new?state=AB12t` + +## Sharing your {% data variables.product.prodname_github_app %} with {% data variables.product.prodname_ghe_server %} instances + +If you want to share your {% data variables.product.prodname_github_app %} with {% data variables.product.prodname_ghe_server %} instances that you are not part of, you need to take additional steps. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-your-github-app-available-for-github-enterprise-server)." diff --git a/content/apps/using-github-apps/about-using-github-apps.md b/content/apps/using-github-apps/about-using-github-apps.md index 225515a2819b..1877021dfc44 100644 --- a/content/apps/using-github-apps/about-using-github-apps.md +++ b/content/apps/using-github-apps/about-using-github-apps.md @@ -34,4 +34,10 @@ Before you install or authorize a {% data variables.product.prodname_github_app ## {% data variables.product.prodname_github_app %}s and OAuth Apps -{% data variables.product.company_short %} also supports OAuth Apps. Unlike {% data variables.product.prodname_github_app %}s, you do not install an OAuth App or control what repositories it can access. For more information, see "[AUTOTITLE](/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps)." +{% data variables.product.company_short %} also supports {% data variables.product.prodname_oauth_app %}s. Unlike {% data variables.product.prodname_github_app %}s, you do not install an {% data variables.product.prodname_oauth_app %} or control what repositories it can access. + +Both {% data variables.product.prodname_oauth_app %}s and {% data variables.product.prodname_github_app %}s use OAuth 2.0. + +{% data variables.product.prodname_oauth_app %}s can only act on behalf of a user while {% data variables.product.prodname_github_app %}s can either act on behalf of a user or independently of a user. + +For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)" and "[AUTOTITLE](/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps)." diff --git a/content/apps/using-github-apps/authorizing-github-apps.md b/content/apps/using-github-apps/authorizing-github-apps.md index d1f3d9c2cadf..117ec8a23ffa 100644 --- a/content/apps/using-github-apps/authorizing-github-apps.md +++ b/content/apps/using-github-apps/authorizing-github-apps.md @@ -1,5 +1,6 @@ --- title: Authorizing GitHub Apps +shortTitle: Authorize intro: 'You can authorize a {% data variables.product.prodname_github_app %} to retrieve information about your {% data variables.product.company_short %} account and to make changes on your behalf.' versions: fpt: '*' @@ -17,9 +18,9 @@ redirect_from: ## About authorizing {% data variables.product.prodname_github_app %}s -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. 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. +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. -During authorization, you'll be prompted to grant the {% data variables.product.prodname_github_app %} permission to do all of the following: +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: * Verify your {% data variables.product.company_short %} identity: When authorized, the {% data variables.product.prodname_github_app %} will be able to retrieve your public GitHub profile. The app may also be able to retrieve some private account information. During the authorization process, {% data variables.product.company_short %} will tell you which account information the {% data variables.product.prodname_github_app %} will be able to access. * Know which resources you can access: When authorized, the {% data variables.product.prodname_github_app %} will be able to determine which resources you can access that the app can also access. The app may use this, for example, so that it can show you an appropriate list of repositories. @@ -27,20 +28,20 @@ During authorization, you'll be prompted to grant the {% data variables.product. You can review and revoke your authorization at any time. For more information, see "[AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations)." -## Difference between authorization and installation - -{% data reusables.apps.install-vs-authorize %} - -For more information about installation, see {% ifversion ghec or fpt %}"[AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-personal-account)" and "[AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-organization)."{% else %}"[AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps)."{% endif %} - ## About {% data variables.product.prodname_github_app %}s acting on your behalf Once you authorize a {% data variables.product.prodname_github_app %}, the app can act on your behalf. The situations in which a {% data variables.product.prodname_github_app %} acts on your behalf vary according to the purpose of the {% data variables.product.prodname_github_app %} and the context in which it is being used. For example, an integrated development environment (IDE) may use a {% data variables.product.prodname_github_app %} to interact on your behalf in order to push changes you have authored through the IDE back to repositories on {% data variables.product.company_short %}. -The {% data variables.product.prodname_github_app %} can only do things that both you and the app have permission to do. For example, if you have write access to a repository but the {% data variables.product.prodname_github_app %} only has read access, then the app can only read the contents of the repository even when it is acting on your behalf. Similarly, if you have access to repositories `A` and `B`, and the {% data variables.product.prodname_github_app %} has access to repositories `B` and `C`, then the app can only access repository `B` when acting on your behalf. +The {% data variables.product.prodname_github_app %} can only do things that both you and the app have permission to do. For example, if you have write access to a repository but the {% data variables.product.prodname_github_app %} only has read access, then the app can only read the contents of the repository even when it is acting on your behalf. Similarly, if you have access to repositories `A` and `B`, and the {% data variables.product.prodname_github_app %} has access to repositories `B` and `C`, then the app can only access repository `B` when acting on your behalf. For more information about the permissions granted to a {% data variables.product.prodname_github_app %}, see "[Difference between authorization and installation](#difference-between-authorization-and-installation)." When an app acts on your behalf, it will attribute the activity to you in conjunction with the app. For example, if the app posts a comment on your behalf, the {% data variables.product.company_short %} UI will show your avatar photo along with the app's identicon badge as the author of the issue. ![Screenshot of a comment that has a user avatar with an overlaid app identicon badge. The avatar is highlighted with an orange outline.](/assets/images/help/apps/github-app-acting-on-your-behalf.png) Similarly, if the activity triggers a corresponding entry in the audit logs and security logs, the logs will list you as the actor but will state that the "programmatic_access_type" is "GitHub App user-to-server token". + +## Difference between authorization and installation + +{% data reusables.apps.install-vs-authorize %} + +For more information about installation, see "[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party)," {% ifversion ghec or fpt %}"[AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-personal-account)" and "[AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-organization)."{% else %}"[AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps)."{% endif %} diff --git a/content/apps/using-github-apps/index.md b/content/apps/using-github-apps/index.md index e6e6a2bdb932..8cd7d85dfca6 100644 --- a/content/apps/using-github-apps/index.md +++ b/content/apps/using-github-apps/index.md @@ -15,10 +15,11 @@ children: - /about-using-github-apps - /installing-a-github-app-from-github-marketplace-for-your-personal-account - /installing-a-github-app-from-github-marketplace-for-your-organizations + - /installing-your-own-github-app - /installing-a-github-app-from-a-third-party - /authorizing-github-apps - - /reviewing-and-revoking-authorization-of-github-apps - /approving-updated-permissions-for-a-github-app + - /reviewing-and-revoking-authorization-of-github-apps - /reviewing-and-modifying-installed-github-apps --- diff --git a/content/apps/maintaining-github-apps/installing-your-own-github-app.md b/content/apps/using-github-apps/installing-your-own-github-app.md similarity index 88% rename from content/apps/maintaining-github-apps/installing-your-own-github-app.md rename to content/apps/using-github-apps/installing-your-own-github-app.md index 4fc069e314fa..825a6f73ed02 100644 --- a/content/apps/maintaining-github-apps/installing-your-own-github-app.md +++ b/content/apps/using-github-apps/installing-your-own-github-app.md @@ -1,11 +1,12 @@ --- title: Installing your own GitHub App -intro: 'You can install your {% data variables.product.prodname_github_app %} on the user or organization account that owns the app. If your app is public, the {% data variables.product.prodname_github_app %} can also be installed on other accounts.' +intro: 'You can install a {% data variables.product.prodname_github_app %} that you created on the user or organization account that owns the app. If your app is public, the {% data variables.product.prodname_github_app %} can also be installed on other accounts.' redirect_from: - /apps/installing-github-apps - /developers/apps/installing-github-apps - /developers/apps/managing-github-apps/installing-github-apps - /apps/maintaining-github-apps/installing-github-apps + - /apps/maintaining-github-apps/installing-your-own-github-app versions: fpt: '*' ghes: '*' @@ -13,7 +14,7 @@ versions: ghec: '*' topics: - GitHub Apps -shortTitle: Install your app +shortTitle: Install your own app --- ## About installing your own {% data variables.product.prodname_github_app %} diff --git a/content/apps/using-github-apps/reviewing-and-modifying-installed-github-apps.md b/content/apps/using-github-apps/reviewing-and-modifying-installed-github-apps.md index 5d5637cbaade..ff9328e73e00 100644 --- a/content/apps/using-github-apps/reviewing-and-modifying-installed-github-apps.md +++ b/content/apps/using-github-apps/reviewing-and-modifying-installed-github-apps.md @@ -1,6 +1,6 @@ --- title: Reviewing and modifying installed GitHub Apps -shortTitle: Review and modify +shortTitle: Review installations intro: "You can review the permissions and change the repository access for {% data variables.product.prodname_github_app %}s that you have installed. You can also temporarily or permanently prevent a {% data variables.product.prodname_github_app %} from accessing resources owned by your account or organization." versions: fpt: '*' diff --git a/content/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps.md b/content/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps.md index eba27a807e0b..861630c68b94 100644 --- a/content/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps.md +++ b/content/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps.md @@ -15,7 +15,7 @@ versions: topics: - Identity - Access management -shortTitle: Authorized integrations +shortTitle: Review your authorizations --- ## About authorized {% data variables.product.prodname_github_apps %} diff --git a/data/reusables/apps/install-vs-authorize.md b/data/reusables/apps/install-vs-authorize.md index 20daf3edc48a..64b726e836fb 100644 --- a/data/reusables/apps/install-vs-authorize.md +++ b/data/reusables/apps/install-vs-authorize.md @@ -1,5 +1,14 @@ -When you install a {% data variables.product.prodname_github_app %} on your account or organization, you grant the app permission to access the organization and repository resources that it requested. You also specify which repositories the app can access. +When you **install** a {% data variables.product.prodname_github_app %} on your account or organization, you grant the app permission to access the organization and repository resources that it requested. You also specify which repositories the app can access. During the installation process, the {% data variables.product.prodname_github_app %} will indicate which repository and organization permissions you are granting. For more information about what different permissions enable a {% data variables.product.prodname_github_app %} to do, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)." -When you authorize a {% data variables.product.prodname_github_app %} you grant the app access to your GitHub account, based on the account permissions the app requested. You also grant the app permission to act on your behalf. + +For example, you might grant the {% data variables.product.prodname_github_app %} permission to write issues and read repository metadata, and you might grant the {% data variables.product.prodname_github_app %} access to all of your repositories. + +![Screenshot of the page to install a GitHub App. The app is requesting read access to metadata and write access to issues. The app can also request user authorization for read access to emails and write access to gists.](/assets/images/github-apps/install_app.png) + +When you **authorize** a {% data variables.product.prodname_github_app %}, you grant the app access to your {% data variables.product.prodname_dotcom %} account, based on the account permissions the app requested. During the authorization process, the app will indicate which resources the app can access on your account. When you authorize a {% data variables.product.prodname_github_app %}, you also grant the app permission to act on your behalf. + +For example, you might grant the {% data variables.product.prodname_github_app %} permission to view your email addresses and write Gists. + +![Screenshot of the page to authorize a GitHub App. The app is requesting read access to email and write access to gists.](/assets/images/github-apps/authorize_app.png) You can install a {% data variables.product.prodname_github_app %} without authorizing the app. Similarly, you can authorize the app without installing the app.