From 046410ee42c53bf06b04baa30c085aa0766ad0c5 Mon Sep 17 00:00:00 2001 From: Kyle Smith Date: Mon, 13 Sep 2021 14:58:59 -0400 Subject: [PATCH] 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