From 8d88ba28ea6d10f1c58259131f84e0fa3dbc51b4 Mon Sep 17 00:00:00 2001 From: Tim Hansen Date: Wed, 24 Mar 2021 10:50:28 -0600 Subject: [PATCH] Update descriptions, remove $env, wording tweaks Signed-off-by: Tim Hansen --- docs/integrations/azure/locations.md | 10 +++++----- docs/integrations/bitbucket/locations.md | 21 ++++++++++----------- docs/integrations/github/discovery.md | 4 +++- docs/integrations/github/locations.md | 12 +++++------- docs/integrations/github/org.md | 5 ++--- docs/integrations/gitlab/locations.md | 12 +++++------- docs/integrations/index.md | 15 +++++++-------- docs/integrations/ldap/org.md | 6 ++---- 8 files changed, 39 insertions(+), 46 deletions(-) diff --git a/docs/integrations/azure/locations.md b/docs/integrations/azure/locations.md index 13de79821a..4ce19bad4e 100644 --- a/docs/integrations/azure/locations.md +++ b/docs/integrations/azure/locations.md @@ -2,11 +2,12 @@ id: locations title: Azure DevOps Locations sidebar_label: Locations -description: Documentation on Azure DevOps location integration +description: + Integrating source code stored in Azure DevOps into the Backstage catalog --- The Azure integration supports loading catalog entities from Azure DevOps. -Components can be added to +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) @@ -16,8 +17,7 @@ plugin. integrations: azure: - host: dev.azure.com - token: - $env: AZURE_TOKEN + token: ${AZURE_TOKEN} ``` > Note: An Azure DevOps provider is added automatically at startup for @@ -27,4 +27,4 @@ integrations: The configuration is a structure with two elements: - `host`: The DevOps host; only `dev.azure.com` is supported. -- `token` (optional): An personal access token as expected by Azure DevOps. +- `token` (optional): A personal access token as expected by Azure DevOps. diff --git a/docs/integrations/bitbucket/locations.md b/docs/integrations/bitbucket/locations.md index dd65146b63..bf7a6af57c 100644 --- a/docs/integrations/bitbucket/locations.md +++ b/docs/integrations/bitbucket/locations.md @@ -2,11 +2,12 @@ id: locations title: BitBucket Locations sidebar_label: Locations -description: Documentation on BitBucket location integration +description: + Integrating source code stored in BitBucket into the Backstage catalog --- The BitBucket integration supports loading catalog entities from bitbucket.com -or a self-hosted BitBucket. Components can be added to +or a self-hosted BitBucket. 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) @@ -16,10 +17,8 @@ plugin. integrations: bitbucket: - host: bitbucket.org - username: - $env: BITBUCKET_USERNAME - token: - $env: BITBUCKET_TOKEN + username: ${BITBUCKET_USERNAME} + token: ${BITBUCKET_TOKEN} ``` > Note: A public BitBucket provider is added automatically at startup for @@ -31,12 +30,12 @@ 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`. -- `username`: The BitBucket username to use in API requests. If a username is - not supplied, anonymous access will be used. - `token` (optional): An personal access token as expected by BitBucket. Either - an access token **or** a password may be supplied. -- `appPassword` (optional): The password for the BitBucket user. Either an - appPassword **or** an access token may be supplied. + an access token **or** a username + appPassword may be supplied. +- `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 + when using `username` instead of `token`. - `apiBaseUrl` (optional): The URL of the GitLab API. For self-hosted installations, it is commonly at `https:///api/v4`. For gitlab.com, this configuration is not needed as it can be inferred. diff --git a/docs/integrations/github/discovery.md b/docs/integrations/github/discovery.md index 9bea4e3978..e2c30bf179 100644 --- a/docs/integrations/github/discovery.md +++ b/docs/integrations/github/discovery.md @@ -2,7 +2,9 @@ id: discovery title: GitHub Discovery sidebar_label: Discovery -description: Documentation on GitHub organization discovery +description: + Automatically discovering catalog entities from repositories in a GitHub + organization --- The GitHub integration has a special discovery processor for discovering catalog diff --git a/docs/integrations/github/locations.md b/docs/integrations/github/locations.md index 498da0f24d..7976c1dfa9 100644 --- a/docs/integrations/github/locations.md +++ b/docs/integrations/github/locations.md @@ -2,11 +2,11 @@ id: locations title: GitHub Locations sidebar_label: Locations -description: Documentation on GitHub location integration +description: Integrating source code stored in GitHub into the Backstage catalog --- The GitHub integration supports loading catalog entities from github.com or -GitHub Enterprise. Components can be added to +GitHub Enterprise. Entities can be added to [static catalog configuration](../../features/software-catalog/configuration.md), registered with the [catalog-import](https://github.com/backstage/backstage/tree/master/plugins/catalog-import) @@ -21,13 +21,11 @@ To use this integration, add configuration to your root `app-config.yaml`: integrations: github: - host: github.com - token: - $env: GITHUB_TOKEN + token: ${GITHUB_TOKEN} - host: ghe.example.net apiBaseUrl: https://ghe.example.net/api/v3 rawBaseUrl: https://ghe.example.net/raw - token: - $env: GHE_TOKEN + token: ${GHE_TOKEN} ``` > Note: A public GitHub provider is added automatically at startup for @@ -52,7 +50,7 @@ data from. Each entry is a structure with up to four elements: with this provider, specify the base URL for its endpoint here, with no trailing slash. Specifically when the target is public GitHub, you can leave it out to be inferred automatically. For a GitHub Enterprise installation, it - is commonly at `https://api.` or `https:///api/v3`. + is commonly at `https:///raw`. You need to supply either `apiBaseUrl` or `rawBaseUrl` or both (except for public GitHub, for which we can infer them). The `apiBaseUrl` will always be diff --git a/docs/integrations/github/org.md b/docs/integrations/github/org.md index 848a306381..f31c42dcd9 100644 --- a/docs/integrations/github/org.md +++ b/docs/integrations/github/org.md @@ -3,7 +3,7 @@ id: org title: GitHub Organizational Data sidebar_label: Org Data # prettier-ignore -description: Setting up ingestion of organizational data from GitHub +description: Importing users and groups from a GitHub organization into Backstage --- The Backstage catalog can be set up to ingest organizational data - teams and @@ -46,8 +46,7 @@ catalog: providers: - target: https://github.com apiBaseUrl: https://api.github.com - token: - $env: GITHUB_TOKEN + token: ${GITHUB_TOKEN} ``` Locations point out the specific org(s) you want to import. The `type` of these diff --git a/docs/integrations/gitlab/locations.md b/docs/integrations/gitlab/locations.md index 8694cb8119..965d183a9d 100644 --- a/docs/integrations/gitlab/locations.md +++ b/docs/integrations/gitlab/locations.md @@ -2,11 +2,11 @@ id: locations title: GitLab Locations sidebar_label: Locations -description: Documentation on GitLab location integration +description: Integrating source code stored in GitLab into the Backstage catalog --- The GitLab integration supports loading catalog entities from gitlab.com or a -self-hosted GitLab. Components can be added to +self-hosted GitLab. 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) @@ -16,8 +16,7 @@ plugin. integrations: gitlab: - host: gitlab.com - token: - $env: GITLAB_TOKEN + token: ${GITLAB_TOKEN} ``` > Note: A public GitLab provider is added automatically at startup for @@ -29,9 +28,8 @@ can list the GitLab providers you want to fetch data from. Each entry is a structure with up to four elements: - `host`: The host of the GitLab instance, e.g. `gitlab.company.com`. -- `token` (optional): An authentication token as expected by GitLab. If - supplied, it will be passed along with all calls to this provider, both API - and raw. If it is not supplied, anonymous access will be used. +- `token` (optional): An authentication token as expected by GitLab. If this is + not supplied, anonymous access will be used. - `apiBaseUrl` (optional): The URL of the GitLab API. For self-hosted installations, it is commonly at `https:///api/v4`. For gitlab.com, this configuration is not needed as it can be inferred. diff --git a/docs/integrations/index.md b/docs/integrations/index.md index d54e1f630a..baa280d620 100644 --- a/docs/integrations/index.md +++ b/docs/integrations/index.md @@ -2,7 +2,9 @@ id: index title: Integrations sidebar_label: Overview -description: Documentation on Backstage Integrations +description: + Configuring Backstage to read or publish data with external providers using + integrations --- Integrations allow Backstage to read or publish data using external providers @@ -11,7 +13,7 @@ Integrations allow Backstage to read or publish data using external providers ## Configuration -Integration are configured at the root level of `app-config.yaml` since +Integrations are configured at the root level of `app-config.yaml` since integrations are used by many Backstage core features and other plugins. Each key under `integrations` is a separate configuration for a single external @@ -22,14 +24,11 @@ configuration to use both GitHub and BitBucket: integrations: github: - host: github.com - token: - $env: GITHUB_TOKEN + token: ${GITHUB_TOKEN} bitbucket: - host: bitbucket.org - username: - $env: BITBUCKET_USERNAME - appPassword: - $env: BITBUCKET_APP_PASSWORD + username: ${BITBUCKET_USERNAME} + appPassword: ${BITBUCKET_APP_PASSWORD} ``` See documentation for each type of integration for full details on diff --git a/docs/integrations/ldap/org.md b/docs/integrations/ldap/org.md index dea33e4024..fca68333ab 100644 --- a/docs/integrations/ldap/org.md +++ b/docs/integrations/ldap/org.md @@ -46,8 +46,7 @@ catalog: - target: ldaps://ds.example.net bind: dn: uid=ldap-reader-user,ou=people,ou=example,dc=example,dc=net - secret: - $env: LDAP_SECRET + secret: ${LDAP_SECRET} users: dn: ou=people,ou=example,dc=example,dc=net options: @@ -93,8 +92,7 @@ authenticate) towards the server. It has the following fields. ```yaml dn: uid=ldap-reader-user,ou=people,ou=example,dc=example,dc=net -secret: - $env: LDAP_SECRET +secret: ${LDAP_SECRET} ``` The `dn` is the full LDAP DN (distinguished name) for the user that the plugin