docs: Restructure Github apps documentation

Signed-off-by: Johan Haals <johan.haals@gmail.com>

docs/getting-started/configuration.md

@@ -235,7 +235,7 @@ That's settled. This information will be leveraged by other plugins.
 Some helpful links, for if you want to learn more about:
 
 - [Other available integrations](../integrations/)
-- [Using GitHub Apps instead of a Personal Access Token](../plugins/github-apps.md#docsNav)
+- [Using GitHub Apps instead of a Personal Access Token](../integrations/github/github-apps.md#docsNav)
 
 ### Explore what we've done so far
 

docs/integrations/github/discovery.md

@@ -112,11 +112,10 @@ const builder = await CatalogBuilder.create(env);
 builder.setProcessingIntervalSeconds(300);
 ```
 
-Alternatively, or additionally, you can configure [github-apps] authentication
+Alternatively, or additionally, you can configure [github-apps](github-apps.md) authentication
 which carries a much higher rate limit at GitHub.
 
 This is true for any method of adding GitHub entities to the catalog, but
 especially easy to hit with automatic discovery.
 
 [rate limits]: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting
-[github-apps]: ../../plugins/github-apps.md

docs/integrations/github/github-apps.md

@@ -13,6 +13,8 @@ the OAuth apps and their respective scopes.
 
 ## Caveats
 
+- This authentication method is built for authenticating towards
+  organization repositories and not towards personal repositories.
 - It's not possible to have multiple Backstage GitHub Apps installed in the same
   GitHub organization, to be handled by Backstage. We currently don't check
   through all the registered GitHub Apps to see which ones are installed for a
@@ -25,7 +27,7 @@ the OAuth apps and their respective scopes.
   want for github.com but it's recommended to make your application public for
   GitHub Enterprise in order to share application across your GHE organizations.
 
-A GitHub app created with `backstage-cli create-github-app` will have read
+A GitHub app created with the cli will have read
 access by default. You have to manually update the GitHub App settings in GitHub
 to grant the app more permissions if needed.
 
@@ -35,8 +37,12 @@ You can use the `backstage-cli` to create a GitHub App using a manifest file
 that we provide. This gives us a way to automate some of the work required to
 create a GitHub app.
 
+```console
+yarn backstage-cli create-github-app <github org>
+```
+
 You can read more about the
-[`backstage-cli create-github-app` method](../local-dev/cli-commands.md#create-github-app).
+[`backstage-cli create-github-app`](../../local-dev/cli-commands.md#create-github-app) command.
 
 Once you've gone through the CLI command, it should produce a YAML file in the
 root of the project which you can then use as an `include` in your

docs/integrations/github/locations.md

@@ -75,8 +75,6 @@ your use of the integration:
 
 ## Authentication with GitHub Apps
 
-Alternatively, Backstage can use GitHub Apps for backend authentication. This
-has higher rate limits, and a clearer authorization model. See [github-apps] for
+Alternatively for GitHub organizations, Backstage can use GitHub Apps for backend authentication. This
+has higher rate limits, and a clearer authorization model. See [github-apps](github-apps.md) for
 how to set this up.
-
-[github-apps]: ../../plugins/github-apps.md

docs/local-dev/cli-commands.md

@@ -362,7 +362,7 @@ Usage: backstage-cli build-workspace [options] <workspace-dir>
 
 Creates a GitHub App in your GitHub organization. This is an alternative to
 token-based [GitHub integration](../integrations/github/locations.md). See
-[GitHub Apps for Backstage Authentication](../plugins/github-apps.md).
+[GitHub Apps for Backstage Authentication](../integrations/github/github-apps.md).
 
 Launches a browser to create the App through GitHub and saves the result as a
 YAML file that can be referenced in the GitHub integration configuration.

docs/plugins/url-reader.md

@@ -24,7 +24,7 @@ package provides a dedicated API for reading from such URL based remote
 locations like GitHub, GitLab, Bitbucket, Google Cloud Storage, etc. This is
 commonly referred to as "URL Reader". It takes care of making authenticated
 requests to the remote host so that private files can be read securely. If users
-have [GitHub App based authentication](github-apps.md) set up, URL Reader even
+have [GitHub App based authentication](../integrations/github/github-apps.md) set up, URL Reader even
 refreshes the token, to avoid reaching the GitHub API rate limit.
 
 As a result, plugin authors do not have to worry about any of these problems

microsite/sidebars.json

@@ -164,7 +164,8 @@
         "ids": [
           "integrations/github/locations",
           "integrations/github/discovery",
-          "integrations/github/org"
+          "integrations/github/org",
+          "integrations/github/github-apps"
         ]
       },
       {
@@ -202,7 +203,6 @@
           "plugins/proxying",
           "plugins/backend-plugin",
           "plugins/call-existing-api",
-          "plugins/github-apps",
           "plugins/url-reader"
         ]
       },

mkdocs.yml

@@ -105,6 +105,7 @@ nav:
           - Locations: 'integrations/github/locations.md'
           - Discovery: 'integrations/github/discovery.md'
           - Org Data: 'integrations/github/org.md'
+          - GitHub Apps for Backend Authentication: 'integrations/github/github-apps.md'
       - GitLab:
           - Locations: 'integrations/gitlab/locations.md'
           - Discovery: 'integrations/gitlab/discovery.md'
@@ -126,7 +127,6 @@ nav:
           - Proxying: 'plugins/proxying.md'
           - Backend plugin: 'plugins/backend-plugin.md'
           - Call existing API: 'plugins/call-existing-api.md'
-          - GitHub Apps for Backend Authentication: 'plugins/github-apps.md'
           - URL Reader: 'plugins/url-reader.md'
       - Testing:
           - Testing with Jest: 'plugins/testing.md'