Merge pull request #5149 from goober/feature/bitbucket-discovery

Add a Bitbucket Discovery processor

docs/integrations/bitbucket/discovery.md

@@ -0,0 +1,41 @@
+---
+id: discovery
+title: Bitbucket Discovery
+sidebar_label: Discovery
+description:
+  Automatically discovering catalog entities from repositories in Bitbucket
+---
+
+The Bitbucket integration has a special discovery processor for discovering
+catalog entities located in Bitbucket. The processor will crawl your Bitbucket
+account and register entities matching the configured path. This can be useful
+as an alternative to static locations or manually adding things to the catalog.
+
+> Note: The Bitbucket Discovery Processor currently only supports a self-hosted
+> Bitbucket Server, and not the hosted Bitbucket Cloud product.
+
+To use the discovery processor, you'll need a Bitbucket integration
+[set up](locations.md) with a `BITBUCKET_TOKEN` and a `BITBUCKET_API_BASE_URL`.
+Then you can add a location target to the catalog configuration:
+
+```yaml
+catalog:
+  locations:
+    - type: bitbucket-discovery
+      target: https://bitbucket.mycompany.com/projects/my-project/repos/service-*/catalog-info.yaml
+```
+
+Note the `bitbucket-discovery` type, as this is not a regular `url` processor.
+
+The target is composed of four parts:
+
+- The base instance URL, `https://bitbucket.mycompany.com` in this case
+- The project key to scan, which accepts \* wildcard tokens. This can simply be
+  `*` to scan repositories from all projects. This example only scans for
+  repositories in the `my-project` project.
+- The repository blob to scan, which accepts \* wildcard tokens. This can simply
+  be `*` to scan all repositories in the project. This example only looks for
+  repositories prefixed with `service-`.
+- The path within each repository to find the catalog YAML file. This will
+  usually be `/catalog-info.yaml` or a similar variation for catalog files
+  stored in the root directory of each repository.

docs/integrations/bitbucket/locations.md

@@ -1,12 +1,12 @@
 ---
 id: locations
-title: BitBucket Locations
+title: Bitbucket Locations
 sidebar_label: Locations
 description:
-  Integrating source code stored in BitBucket into the Backstage catalog
+  Integrating source code stored in Bitbucket into the Backstage catalog
 ---
 
-The BitBucket integration supports loading catalog entities from bitbucket.com
+The Bitbucket integration supports loading catalog entities from bitbucket.org
 or a self-hosted BitBucket. Entities can be added to
 [static catalog configuration](../../features/software-catalog/configuration.md),
 or registered with the
@@ -21,21 +21,21 @@ integrations:
       token: ${BITBUCKET_TOKEN}
 ```
 
-> Note: A public BitBucket provider is added automatically at startup for
+> Note: A public Bitbucket provider is added automatically at startup for
 > convenience, so you only need to list it if you want to supply a
 > [token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html).
 
 Directly under the `bitbucket` key is a list of provider configurations, where
-you can list the BitBucket providers you want to fetch data from. Each entry is
+you can list the Bitbucket providers you want to fetch data from. Each entry is
 a structure with up to four elements:
 
-- `host`: The host of the BitBucket instance, e.g. `bitbucket.company.com`.
-- `token` (optional): An personal access token as expected by BitBucket. Either
+- `host`: The host of the Bitbucket instance, e.g. `bitbucket.company.com`.
+- `token` (optional): An personal access token as expected by Bitbucket. Either
   an access token **or** a username + appPassword may be supplied.
-- `username`: The BitBucket username to use in API requests. If neither a
+- `username`: The Bitbucket username to use in API requests. If neither a
   username nor token are supplied, anonymous access will be used.
-- `appPassword` (optional): The password for the BitBucket user. Only needed
+- `appPassword` (optional): The password for the Bitbucket user. Only needed
   when using `username` instead of `token`.
-- `apiBaseUrl` (optional): The URL of the GitLab API. For self-hosted
-  installations, it is commonly at `https://<host>/api/v4`. For gitlab.com, this
-  configuration is not needed as it can be inferred.
+- `apiBaseUrl` (optional): The URL of the Bitbucket API. For self-hosted
+  installations, it is commonly at `https://<host>/rest/api/1.0`. For
+  bitbucket.org, this configuration is not needed as it can be inferred.