diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md index 4ba83146db..953540227c 100644 --- a/docs/features/software-catalog/index.md +++ b/docs/features/software-catalog/index.md @@ -19,7 +19,7 @@ are then harvested and visualized in Backstage. ## How it works -Backstage and the Backstage Service Catalog makes it easy for one team to manage +Backstage and the Backstage Service Catalog make it easy for one team to manage 10 services — and makes it possible for your company to manage thousands of them. diff --git a/docs/features/software-templates/adding-templates.md b/docs/features/software-templates/adding-templates.md index 5a4e0049ab..75a75003f7 100644 --- a/docs/features/software-templates/adding-templates.md +++ b/docs/features/software-templates/adding-templates.md @@ -5,8 +5,8 @@ description: Documentation on Adding your own Templates --- Templates are stored in the **Service Catalog** under a kind `Template`. The -minimum that the template skeleton needs is a `template.yaml` but it would be -good to also have some files in there that can be templated in. +minimum that is needed to define a template is a `template.yaml` file, but it +would be good to also have some files in there that can be templated in. A simple `template.yaml` definition might look something like this: @@ -61,7 +61,7 @@ support to load the location will also need to be added to the Catalog. You can add the template files to the catalog through [static location configuration](../software-catalog/configuration.md#static-location-configuration), -for example +for example: ```yaml catalog: @@ -100,11 +100,11 @@ curl \ --location \ --request POST 'localhost:7000/api/catalog/locations' \ --header 'Content-Type: application/json' \ - --data-raw "{\"type\": \"github\", \"target\": \"https://${YOUR GITHUB REPO}blob/master/${PATH TO FOLDER}/template.yaml\"}" + --data-raw "{\"type\": \"github\", \"target\": \"https://${GITHUB URL}/${YOUR GITHUB ORG/REPO}/blob/master/${PATH TO FOLDER}/template.yaml\"}" ``` -This should then have added the catalog, and also should now be listed under the -create page at http://localhost:3000/create. +This should then have been added the catalog, and be listed under the create +page at http://localhost:3000/create. The `type` field which is chosen in the request to add the `template.yaml` to the Service Catalog here, will become the `PreparerKey` which will be used to diff --git a/docs/features/software-templates/extending/create-your-own-preparer.md b/docs/features/software-templates/extending/create-your-own-preparer.md index 80287c6ce1..ef9d709bce 100644 --- a/docs/features/software-templates/extending/create-your-own-preparer.md +++ b/docs/features/software-templates/extending/create-your-own-preparer.md @@ -15,10 +15,10 @@ location protocols: - `github://` These two are added to the `PreparersBuilder` and then passed into the -`createRouter` function of the `@spotify/plugin-scaffolder-backend` +`createRouter` function of the `@spotify/plugin-scaffolder-backend`. -A full example backend can be found -[here](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts), +A full example backend can be found in +[`scaffolder.ts`](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts), but it looks something like the following ```ts @@ -56,7 +56,7 @@ when added to the service catalog. You can see more about this `PreparerKey` here in [Register your own template](../adding-templates.md) **note:** Currently the catalog supports loading definitions from GitHub + Local -Files, which translate into the two `PreparerKeys` `file` and `github`. To load +Files, which translate into the two `PreparerKeys`: `file` and `github`. To load from other places, not only will there need to be another preparer, but the support to load the location will also need to be added to the Catalog. diff --git a/docs/features/software-templates/index.md b/docs/features/software-templates/index.md index ae121f8029..3ebb426466 100644 --- a/docs/features/software-templates/index.md +++ b/docs/features/software-templates/index.md @@ -39,17 +39,17 @@ internally. ![Enter some variables](../../assets/software-templates/template-picked.png) After filling in these variables, you'll get some more fields to fill out which -are required for backstage usage: the owner, (which is a `user` in the backstage +are required for backstage usage: the owner (which is a `user` in the backstage system), the `storePath` (which right now must be a GitHub Organisation or -GitHub user), a non-existing github repository name in the format -`organisation/reponame`, and a GitHub team or user account which should be +GitHub user and a non-existing GitHub repository name in the format +`organisation/reponame`), and a GitHub team or user account which should be granted admin access to the repository. ![Enter backstage vars](../../assets/software-templates/template-picked-2.png) ### Run! -Once you've entered values and confirmed, you'll then get a modal with live +Once you've entered values and confirmed, you'll then get a popup box with live progress of what is currently happening with the creation of your template. ![Templating Running](../../assets/software-templates/running.png) @@ -70,6 +70,6 @@ you to the registered component in the catalog: ![Catalog](../../assets/software-templates/go-to-catalog.png) -And then you'll also be able to see it in the Catalog View table +And then you'll also be able to see it in the Catalog View table: ![Catalog](../../assets/software-templates/added-to-the-catalog-list.png) diff --git a/docs/features/software-templates/installation.md b/docs/features/software-templates/installation.md index 838c5e2d11..842c59e289 100644 --- a/docs/features/software-templates/installation.md +++ b/docs/features/software-templates/installation.md @@ -211,22 +211,16 @@ docs on creating private GitHub access tokens is available Note that the need for private GitHub access tokens will be replaced with GitHub Apps integration further down the line. -#### Github +#### GitHub -The Github access token is retrieved from environment variables via the config. +The GitHub access token is retrieved from environment variables via the config. The config file needs to specify what environment variable the token is retrieved from. Your config should have the following objects. You can configure who can see the new repositories that the scaffolder creates by specifying `visibility` option. Valid options are `public`, `private` and -`internal`. `internal` options is for GitHub Enterprise clients, which means -public within the organization. - -#### Gitlab - -For Gitlab, we currently support the configuration of the GitLab publisher and -allows to configure the private access token and the base URL of a GitLab -instance: +`internal`. The `internal` option is for GitHub Enterprise clients, which means +public within the enterprise. ```yaml scaffolder: @@ -234,6 +228,16 @@ scaffolder: token: $env: GITHUB_TOKEN visibility: public # or 'internal' or 'private' +``` + +#### GitLab + +For GitLab, we currently support the configuration of the GitLab publisher and +allows to configure the private access token and the base URL of a GitLab +instance: + +```yaml +scaffolder: gitlab: api: baseUrl: https://gitlab.com