Add docs for plugin-catalog-backend-module-bitbucket-server
Signed-off-by: Otto Nordander <otto.nordander@resurs.se>
This commit is contained in:
Otto Nordander
@@ -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
|
||||
|
||||
@@ -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<Router> {
|
||||
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)
|
||||
+11
-12
@@ -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://<host>/rest/api/1.0`.
|
||||
@@ -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",
|
||||
|
||||
+3
-1
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user