From 046410ee42c53bf06b04baa30c085aa0766ad0c5 Mon Sep 17 00:00:00 2001 From: Kyle Smith Date: Mon, 13 Sep 2021 14:58:59 -0400 Subject: [PATCH 1/2] Include example of catalog.ts update for discovery interval change. Signed-off-by: Kyle Smith --- docs/integrations/github/discovery.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/integrations/github/discovery.md b/docs/integrations/github/discovery.md index a578d0893d..db4952f904 100644 --- a/docs/integrations/github/discovery.md +++ b/docs/integrations/github/discovery.md @@ -38,17 +38,28 @@ The target is composed of three parts: ## GitHub API Rate Limits -GitHub -[rate limits](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting) -API requests to 5,000 per hour (or more for Enterprise accounts). The default -Backstage catalog backend refreshes data every 100 seconds, which issues an API -request for each discovered location. +GitHub [rate limits] API requests to 5,000 per hour (or more for Enterprise +accounts). The default Backstage catalog backend refreshes data every 100 +seconds, which issues an API request for each discovered location. This means if you have more than ~140 catalog entities, you may get throttled by rate limiting. This will soon be resolved once catalog refreshes make use of ETags; to work around this in the meantime, you can change the refresh rate of -the catalog in your `packages/backend/src/plugins/catalog.ts` file, or configure -Backstage to use the [github-apps plugin](../../plugins/github-apps.md). +the catalog in your `packages/backend/src/plugins/catalog.ts` file: + +```typescript +const builder = await CatalogBuilder.create(env); + +// For example, to refresh every 5 minutes (300 seconds). +builder.setRefreshIntervalSeconds(300); +``` + +Alternatively, or additionally, you can use the [github-apps plugin] 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 plugin]: ../../plugins/github-apps.md From 0dea4449f46c902a8da554bda6fa256fedc82cdd Mon Sep 17 00:00:00 2001 From: Kyle Smith Date: Thu, 23 Sep 2021 10:41:30 -0400 Subject: [PATCH 2/2] update docs Signed-off-by: Kyle Smith --- docs/integrations/github/discovery.md | 6 +++--- docs/integrations/github/locations.md | 6 ++++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/integrations/github/discovery.md b/docs/integrations/github/discovery.md index db4952f904..2096202cd8 100644 --- a/docs/integrations/github/discovery.md +++ b/docs/integrations/github/discovery.md @@ -54,12 +54,12 @@ const builder = await CatalogBuilder.create(env); builder.setRefreshIntervalSeconds(300); ``` -Alternatively, or additionally, you can use the [github-apps plugin] which -carries a much higher rate limit at GitHub. +Alternatively, or additionally, you can configure [github-apps] 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 plugin]: ../../plugins/github-apps.md +[github-apps]: ../../plugins/github-apps.md diff --git a/docs/integrations/github/locations.md b/docs/integrations/github/locations.md index 5b972f332c..330b03eab9 100644 --- a/docs/integrations/github/locations.md +++ b/docs/integrations/github/locations.md @@ -60,5 +60,7 @@ preferred. ## Authentication with GitHub Apps Alternatively, Backstage can use GitHub Apps for backend authentication. This -has higher rate limits, and a clearer authorization model. See the -[github-apps plugin](../../plugins/github-apps.md) for how to set this up. +has higher rate limits, and a clearer authorization model. See [github-apps] for +how to set this up. + +[github-apps]: ../../plugins/github-apps.md