diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index 95fb2afc12..e7d100f410 100644 --- a/docs/getting-started/configuration.md +++ b/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 diff --git a/docs/integrations/github/discovery.md b/docs/integrations/github/discovery.md index 1cbf8905a2..3200a55bd2 100644 --- a/docs/integrations/github/discovery.md +++ b/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 diff --git a/docs/plugins/github-apps.md b/docs/integrations/github/github-apps.md similarity index 93% rename from docs/plugins/github-apps.md rename to docs/integrations/github/github-apps.md index 434c9a4882..67d096af26 100644 --- a/docs/plugins/github-apps.md +++ b/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 +``` + 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 diff --git a/docs/integrations/github/locations.md b/docs/integrations/github/locations.md index 3395c61117..7d3ce632d6 100644 --- a/docs/integrations/github/locations.md +++ b/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 diff --git a/docs/local-dev/cli-commands.md b/docs/local-dev/cli-commands.md index eadb30b878..715d586545 100644 --- a/docs/local-dev/cli-commands.md +++ b/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. diff --git a/docs/plugins/url-reader.md b/docs/plugins/url-reader.md index 0072c34cfb..8a84f3e1ff 100644 --- a/docs/plugins/url-reader.md +++ b/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 diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 092228ae4c..db6d903086 100644 --- a/microsite/sidebars.json +++ b/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" ] }, diff --git a/mkdocs.yml b/mkdocs.yml index 5c73516ba6..4323f102b7 100644 --- a/mkdocs.yml +++ b/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'