First round of apps docs audit changes (#37320)

Co-authored-by: Jess Hosman <1183847+jhosman@users.noreply.github.com>
github · May 30, 2023 · 5e0c864 · 5e0c864
1 parent 4c5fff0
commit 5e0c864
Show file tree

Hide file tree

Showing 31 changed files with 110 additions and 46 deletions.
diff --git a/assets/images/github-apps/authorize_app.png b/assets/images/github-apps/authorize_app.png
diff --git a/assets/images/github-apps/install_app.png b/assets/images/github-apps/install_app.png
diff --git a/...apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md b/...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
@@ -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/...apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps.md b/...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/...ithub-apps/setting-up-a-github-app/about-the-user-authorization-callback-url.md b/...ithub-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
@@ -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
@@ -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/...ng-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private.md b/...ng-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/...es/migrating-oauth-apps-to-github-apps.md → ...pp/migrating-oauth-apps-to-github-apps.md b/...es/migrating-oauth-apps-to-github-apps.md → ...pp/migrating-oauth-apps-to-github-apps.md
@@ -5,14 +5,15 @@ 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: '*'
   ghae: '*'
   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/...creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps.md b/...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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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/...th-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app.md b/...th-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
@@ -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
@@ -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/.../creating-a-github-app-from-a-manifest.md → .../creating-a-github-app-from-a-manifest.md b/.../creating-a-github-app-from-a-manifest.md → .../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/...ting-a-github-app-using-url-parameters.md → ...ting-a-github-app-using-url-parameters.md b/...ting-a-github-app-using-url-parameters.md → ...ting-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
@@ -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/...available-for-github-enterprise-server.md → ...available-for-github-enterprise-server.md b/...available-for-github-enterprise-server.md → ...available-for-github-enterprise-server.md
@@ -9,6 +9,8 @@ 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 %}

diff --git a/...ng-github-apps/sharing-your-github-app.md → ...ng-github-apps/sharing-your-github-app.md b/...ng-github-apps/sharing-your-github-app.md → ...ng-github-apps/sharing-your-github-app.md
@@ -7,6 +7,8 @@ versions:
   ghae: '*'
   ghes: '*'
 shortTitle: Share your app
+redirect_from:
+  - /apps/maintaining-github-apps/sharing-your-github-app
 ---
 
 {% ifversion fpt or ghec %}

diff --git 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)."