From 38dfefed0e9b01de655ad3253a1c8d2d0e6e2f83 Mon Sep 17 00:00:00 2001 From: ElaineDeMattosSilvaB Date: Mon, 15 Apr 2024 19:40:57 +0200 Subject: [PATCH] feat: improve documentation Signed-off-by: ElaineDeMattosSilvaB --- docs/integrations/gitlab/discovery.md | 23 ++++++++++--- docs/integrations/gitlab/org.md | 47 +++++++++++++++++++-------- 2 files changed, 52 insertions(+), 18 deletions(-) diff --git a/docs/integrations/gitlab/discovery.md b/docs/integrations/gitlab/discovery.md index 668b0de694..9a588b3796 100644 --- a/docs/integrations/gitlab/discovery.md +++ b/docs/integrations/gitlab/discovery.md @@ -67,13 +67,18 @@ export default async function createPlugin( const builder = await CatalogBuilder.create(env); /* highlight-add-start */ builder.addEntityProvider( - GitlabDiscoveryEntityProvider.fromConfig(env.config, { + ...GitlabDiscoveryEntityProvider.fromConfig(env.config, { logger: env.logger, + // optional: alternatively, use scheduler with schedule defined in app-config.yaml + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 30 }, + timeout: { minutes: 3 }, + }), + // optional: alternatively, use schedule scheduler: env.scheduler, }), ); /* highlight-add-end */ - // .. } ``` @@ -108,6 +113,12 @@ export default async function createPlugin( /* highlight-add-start */ const gitlabProvider = GitlabDiscoveryEntityProvider.fromConfig(env.config, { logger: env.logger, + // optional: alternatively, use scheduler with schedule defined in app-config.yaml + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 30 }, + timeout: { minutes: 3 }, + }), + // optional: alternatively, use schedule scheduler: env.scheduler, }); env.eventBroker.subscribe(gitlabProvider); @@ -123,16 +134,18 @@ export default async function createPlugin( To use the discovery provider, you'll need a GitLab integration [set up](locations.md) with a `token`. Then you can add a provider config per group -to the catalog configuration: +to the catalog configuration. -```yaml +> > NOTE: if you are using the New Backend System, the `schedule` has to be setup in the config, as shown below. + +```yaml title="app-config.yaml" catalog: providers: gitlab: yourProviderId: host: gitlab-host # Identifies one of the hosts set up in the integrations branch: main # Optional. Used to discover on a specific branch - fallbackBranch: main # Optional. Fallback to be used if there is no default branch configured at the Gitlab repository. It is only used, if `branch` is undefined. Uses `master` as default + fallbackBranch: master # Optional. Fallback to be used if there is no default branch configured at the Gitlab repository. It is only used, if `branch` is undefined. Uses `master` as default skipForkedRepos: false # Optional. If the project is a fork, skip repository group: example-group # Optional. Group and subgroup (if needed) to look for repositories. If not present the whole instance will be scanned entityFilename: catalog-info.yaml # Optional. Defaults to `catalog-info.yaml` diff --git a/docs/integrations/gitlab/org.md b/docs/integrations/gitlab/org.md index c748fba1ba..206153d53c 100644 --- a/docs/integrations/gitlab/org.md +++ b/docs/integrations/gitlab/org.md @@ -68,20 +68,27 @@ Add the plugin to the plugin catalog `packages/backend/src/plugins/catalog.ts`: /* highlight-add-next-line */ import { GitlabOrgDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab'; -const builder = await CatalogBuilder.create(env); -/** ... other processors and/or providers ... */ -/* highlight-add-start */ -builder.addEntityProvider( - ...GitlabOrgDiscoveryEntityProvider.fromConfig(env.config, { - logger: env.logger, - // optional: alternatively, use scheduler with schedule defined in app-config.yaml - schedule: env.scheduler.createScheduledTaskRunner({ - frequency: { minutes: 30 }, - timeout: { minutes: 3 }, +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); + /** ... other processors and/or providers ... */ + /* highlight-add-start */ + builder.addEntityProvider( + ...GitlabOrgDiscoveryEntityProvider.fromConfig(env.config, { + logger: env.logger, + // optional: alternatively, use scheduler with schedule defined in app-config.yaml + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 30 }, + timeout: { minutes: 3 }, + }), + // optional: alternatively, use schedule + scheduler: env.scheduler, }), - }), -); -/* highlight-add-end */ + ); + /* highlight-add-end */ + // .. +} ``` #### Installation with Events Support @@ -116,6 +123,12 @@ export default async function createPlugin( env.config, { logger: env.logger, + // optional: alternatively, use scheduler with schedule defined in app-config.yaml + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 30 }, + timeout: { minutes: 3 }, + }), + // optional: alternatively, use schedule scheduler: env.scheduler, }, ); @@ -145,6 +158,8 @@ amount of data, this can take significant time and resources. The token used must have the `read_api` scope, and the Users and Groups fetched will be those visible to the account which provisioned the token. +> > NOTE: if you are using the New Backend System, the `schedule` has to be setup in the config, as shown below. + ```yaml catalog: providers: @@ -153,7 +168,13 @@ catalog: host: gitlab.com orgEnabled: true group: org/teams # Required for gitlab.com when `orgEnabled: true`. Optional for self managed. Must not end with slash. Accepts only groups under the provided path (which will be stripped) + allowInherited: true # Allow groups to be ingested even if there are no direct members. groupPattern: '[\s\S]*' # Optional. Filters found groups based on provided pattern. Defaults to `[\s\S]*`, which means to not filter anything + schedule: # optional; same options as in TaskScheduleDefinition + # supports cron, ISO duration, "human duration" as used in code + frequency: { minutes: 30 } + # supports ISO duration, "human duration" as used in code + timeout: { minutes: 3 } ``` ### Groups