Merge branch 'master' into feature/bitbucket-cloud-discovery

docs/integrations/aws-s3/locations.md

@@ -0,0 +1,42 @@
+---
+id: locations
+sidebar_label: Locations
+title: Amazon Web Services S3 Locations
+# prettier-ignore
+description: Setting up an integration with Amazon Web Services S3
+---
+
+The AWS S3 integration supports loading catalog entities from an S3 Bucket.
+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.
+
+## Configuration
+
+To use this integration, add configuration to your `app-config.yaml`:
+
+```yaml
+integrations:
+  awsS3:
+    - host: amazonaws.com
+      accessKeyId: ${AWS_ACCESS_KEY_ID}
+      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
+```
+
+Then make sure the environment variables `AWS_ACCESS_KEY_ID` and
+`AWS_SECRET_ACCESS_KEY` are set when you run Backstage.
+
+Users with multiple AWS accounts may want to use a role for S3 storage that is
+in a different AWS account. Using the `roleArn` parameter as seen below, you can
+instruct the AWS S3 reader to assume a role before accessing S3:
+
+```yaml
+integrations:
+  awsS3:
+    - host: amazonaws.com
+      accessKeyId: ${AWS_ACCESS_KEY_ID}
+      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
+      roleArn: 'arn:aws:iam::xxxxxxxxxxxx:role/example-role'
+```

docs/integrations/bitbucket/discovery.md

@@ -108,13 +108,11 @@ matching repository is processed.
 repository.
 
 ```typescript
-const customRepositoryParser: BitbucketRepositoryParser = async function* customRepositoryParser({
-  client,
-  repository,
-}) {
-  // Custom logic for interpret the matching repository.
-  // See defaultRepositoryParser for an example
-};
+const customRepositoryParser: BitbucketRepositoryParser =
+  async function* customRepositoryParser({ client, repository }) {
+    // Custom logic for interpret the matching repository.
+    // See defaultRepositoryParser for an example
+  };
 
 const processor = BitbucketDiscoveryProcessor.fromConfig(env.config, {
   parser: customRepositoryParser,

docs/integrations/gitlab/discovery.md

@@ -0,0 +1,36 @@
+---
+id: discovery
+title: GitLab Discovery
+sidebar_label: Discovery
+# prettier-ignore
+description: Automatically discovering catalog entities from repositories in GitLab
+---
+
+The GitLab integration has a special discovery processor for discovering catalog
+entities from GitLab. The processor will crawl the GitLab instance and register
+entities matching the configured path. This can be useful as an alternative to
+static locations or manually adding things to the catalog.
+
+To use the discovery processor, you'll need a GitLab integration
+[set up](locations.md) with a `token`. Then you can add a location target to the
+catalog configuration:
+
+```yaml
+catalog:
+  locations:
+    - type: gitlab-discovery
+      target: https://gitlab.com/group/subgroup/blob/main/catalog-info.yaml
+```
+
+Note the `gitlab-discovery` type, as this is not a regular `url` processor.
+
+The target is composed of three parts:
+
+- The base URL, `https://gitlab.com` in this case
+- The group path, `group/subgroup` in this case. This is optional: If you omit
+  this path the processor will scan the entire GitLab instance instead.
+- The path within each repository to find the catalog YAML file. This will
+  usually be `/blob/main/catalog-info.yaml`, `/blob/master/catalog-info.yaml` or
+  a similar variation for catalog files stored in the root directory of each
+  repository. If you want to use the repository's default branch use the `*`
+  wildcard, e.g.: `/blob/*/catalog-info.yaml`