diff --git a/docs/integrations/bitbucket/discovery.md b/docs/integrations/bitbucket/discovery.md index 285b7cc78b..15ede69a4a 100644 --- a/docs/integrations/bitbucket/discovery.md +++ b/docs/integrations/bitbucket/discovery.md @@ -41,7 +41,7 @@ And then add the processor to your catalog builder: ## Self-hosted Bitbucket Server To use the discovery processor with a self-hosted Bitbucket Server, you'll need -a Bitbucket integration [set up](locations.md) with a `BITBUCKET_TOKEN` and a +a Bitbucket integration [set up](../bitbucketServer/locations.md) with a `BITBUCKET_TOKEN` and a `BITBUCKET_API_BASE_URL`. Then you can add a location target to the catalog configuration: @@ -74,7 +74,7 @@ The target is composed of four parts: ## Bitbucket Cloud To use the discovery processor with Bitbucket Cloud, you'll need a Bitbucket -integration [set up](locations.md) with a `username` and an `appPassword`. Then +integration [set up](../bitbucketCloud/locations.md) with a `username` and an `appPassword`. Then you can add a location target to the catalog configuration: ```yaml diff --git a/docs/integrations/bitbucketServer/discovery.md b/docs/integrations/bitbucketServer/discovery.md new file mode 100644 index 0000000000..57e52d1dae --- /dev/null +++ b/docs/integrations/bitbucketServer/discovery.md @@ -0,0 +1,114 @@ +--- +id: discovery +title: Bitbucket Server Discovery +sidebar_label: Discovery +# prettier-ignore +description: Automatically discovering catalog entities from repositories in Bitbucket Server +--- + +The Bitbucket Server integration has a special entity provider for discovering +catalog files located in Bitbucket Server. +The provider will search your Bitbucket Server account and register catalog files matching the configured path +as Location entity and via following processing steps add all contained catalog entities. +This can be useful as an alternative to static locations or manually adding things to the catalog. + +## Installation + +You will have to add the entity provider in the catalog initialization code of your +backend. The provider is not installed by default, therefore you have to add a +dependency to `@backstage/plugin-catalog-backend-module-bitbucket-server` to your backend +package. + +```bash +# From your Backstage root directory +yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-bitbucket-server +``` + +And then add the entity provider to your catalog builder: + +```diff + // In packages/backend/src/plugins/catalog.ts ++ import { BitbucketServerEntityProvider } from '@backstage/plugin-catalog-backend-module-bitbucket-server'; + + export default async function createPlugin( + env: PluginEnvironment, + ): Promise { + const builder = await CatalogBuilder.create(env); ++ builder.addEntityProvider( ++ BitbucketServerEntityProvider.fromConfig(env.config, { ++ logger: env.logger, ++ schedule: env.scheduler.createScheduledTaskRunner({ ++ frequency: { minutes: 30 }, ++ timeout: { minutes: 3 }, ++ }), ++ }), ++ ); + + // [...] + } +``` + +## Configuration + +To use the entity provider, you'll need a [Bitbucket Server integration set up](locations.md). + +Additionally, you need to configure your entity provider instance(s): + +```yaml +# app-config.yaml + +catalog: + providers: + bitbucketServer: + yourProviderId: # identifies your ingested dataset + host: 'bitbucket.mycompany.com' + catalogPath: /catalog-info.yaml # default value + filters: # optional + projectKey: '^apis-.*$' # optional; RegExp + repoSlug: '^service-.*$' # optional; RegExp +``` + +- **host**: + The host of the Bitbucket Server instance, **note**: the host needs to registered as an integration as well, see [location](locations.md). +- **`catalogPath`** _(optional)_: + Default: `/catalog-info.yaml`. + Path where to look for `catalog-info.yaml` files. + When started with `/`, it is an absolute path from the repo root. +- **filters** _(optional)_: + - **`projectKey`** _(optional)_: + Regular expression used to filter results based on the project key. + - **repoSlug** _(optional)_: + Regular expression used to filter results based on the repo slug. + +## Custom location processing + +The Bitbucket Server Entity Provider will by default emit a location for each +matching repository. However, it is possible to override this functionality and take full control of how each +matching repository is processed. + +`BitbucketServerEntityProvider.fromConfig` takes an optional parameter +`options.parser` where you can set your own parser to be used for each matched +repository. + +```typescript +const provider = BitbucketServerEntityProvider.fromConfig(env.config, { + logger: env.logger, + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 30 }, + timeout: { minutes: 3 }, + }), + parser: async function* customLocationParser(options: { + location: LocationSpec, + client: BitbucketServerClient, + }) { + // Custom logic for interpreting the matching repository + // See defaultBitbucketServerLocationParser for an example + } +); +``` + +## Alternative + +_Deprecated!_ Please raise issues for use cases not covered by the entity provider. + +[You can use the `BitbucketDiscoveryProcessor`.](../bitbucket/discovery.md#self-hosted-bitbucket-server) diff --git a/docs/integrations/bitbucket/locations.md b/docs/integrations/bitbucketServer/locations.md similarity index 64% rename from docs/integrations/bitbucket/locations.md rename to docs/integrations/bitbucketServer/locations.md index 4fbb96bb94..7ff19b8b27 100644 --- a/docs/integrations/bitbucket/locations.md +++ b/docs/integrations/bitbucketServer/locations.md @@ -1,28 +1,25 @@ --- id: locations -title: Bitbucket Locations +title: Bitbucket Server Locations sidebar_label: Locations # prettier-ignore -description: Integrating source code stored in Bitbucket into the Backstage catalog +description: Integrating source code stored in Bitbucket Server into the Backstage catalog --- -The Bitbucket integration supports loading catalog entities from bitbucket.org (Bitbucket Cloud) -or Bitbucket Server. Entities can be added to +The Bitbucket Server integration supports loading catalog entities from Bitbucket Server. +Entities can be added to [static catalog configuration](../../features/software-catalog/configuration.md), or registered with the [catalog-import](https://github.com/backstage/backstage/tree/master/plugins/catalog-import) plugin. -## Bitbucket Cloud - -Please see [the Bitbucket Cloud documentation](../bitbucketCloud/locations.md). - -## Bitbucket Server +## Configuration ```yaml integrations: bitbucketServer: - - host: bitbucket.company.com + - host: bitbucket.mycompany.com + apiBaseUrl: https://bitbucket.mycompany.com/rest/api/1.0 token: ${BITBUCKET_SERVER_TOKEN} ``` @@ -32,6 +29,7 @@ or with Basic Auth integrations: bitbucketServer: - host: bitbucket.company.com + apiBaseUrl: https://bitbucket.mycompany.com/rest/api/1.0 username: ${BITBUCKET_SERVER_USERNAME} password: ${BITBUCKET_SERVER_PASSWORD} ``` @@ -40,13 +38,14 @@ Directly under the `bitbucketServer` key is a list of provider configurations, w you can list the Bitbucket Server providers you want to fetch data from. Each entry is a structure with the following elements: -- `host`: The host of the Bitbucket Server instance, e.g. `bitbucket.company.com`. +- `host`: The host of the Bitbucket Server instance, e.g. `bitbucket.mycompany.com`. - `token` (optional): - An [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) + A [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) as expected by Bitbucket Server. - `username` (optional): use for [Basic Auth](https://developer.atlassian.com/server/bitbucket/how-tos/command-line-rest/#authentication) for Bitbucket Server. - `password` (optional): use for [Basic Auth](https://developer.atlassian.com/server/bitbucket/how-tos/command-line-rest/#authentication) for Bitbucket Server. + Note: a token can also be used as a substitute for the password, see [HTTP access tokens](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html). - `apiBaseUrl` (optional): The URL of the Bitbucket Server API. For self-hosted installations, it is commonly at `https:///rest/api/1.0`. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 314710b800..2ae7f5e81d 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -150,10 +150,7 @@ { "type": "subcategory", "label": "Bitbucket", - "ids": [ - "integrations/bitbucket/locations", - "integrations/bitbucket/discovery" - ] + "ids": ["integrations/bitbucket/discovery"] }, { "type": "subcategory", @@ -163,6 +160,14 @@ "integrations/bitbucketCloud/discovery" ] }, + { + "type": "subcategory", + "label": "Bitbucket Server", + "ids": [ + "integrations/bitbucketServer/locations", + "integrations/bitbucketServer/discovery" + ] + }, { "type": "subcategory", "label": "Datadog", diff --git a/mkdocs.yml b/mkdocs.yml index 03c9dee8d0..bf577e53a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -95,11 +95,13 @@ nav: - Discovery: 'integrations/azure/discovery.md' - Org Data: 'integrations/azure/org.md' - Bitbucket: - - Locations: 'integrations/bitbucket/locations.md' - Discovery: 'integrations/bitbucket/discovery.md' - Bitbucket Cloud: - Locations: 'integrations/bitbucketCloud/locations.md' - Discovery: 'integrations/bitbucketCloud/discovery.md' + - Bitbucket Server: + - Locations: 'integrations/bitbucketServer/locations.md' + - Discovery: 'integrations/bitbucketServer/discovery.md' - Datadog: - Installation: 'integrations/datadog-rum/installation.md' - Gerrit: