Clarifications to software template documentation (#3070)
* Clarify scaffolders * Tweak preparer * Template clarifications * Minor wording for clarity * Change wording
This commit is contained in:
Adam Harvey
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -39,17 +39,17 @@ internally.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
@@ -70,6 +70,6 @@ you to the registered component in the catalog:
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user