Merge branch 'master' of github.com:spotify/backstage into shmidt-i/circle-ci-plugin-new-route-api
This commit is contained in:
Ivan Shmidt
@@ -235,6 +235,9 @@ The `backstage.io/` prefix is reserved for use by Backstage core components.
|
||||
|
||||
Values can be of any length, but are limited to being strings.
|
||||
|
||||
There is a list of [well-known annotations](well-known-annotations.md), but
|
||||
anybody is free to add more annotations as they see fit.
|
||||
|
||||
### `tags` [optional]
|
||||
|
||||
A list of single-valued strings, for example to classify catalog entities in
|
||||
@@ -290,7 +293,7 @@ Exactly equal to `backstage.io/v1alpha1` and `Component`, respectively.
|
||||
|
||||
The type of component as a string, e.g. `website`. This field is required.
|
||||
|
||||
The software catalog accepts any type value, but an organisation should take
|
||||
The software catalog accepts any type value, but an organization should take
|
||||
great care to establish a proper taxonomy for these. Tools including Backstage
|
||||
itself may read this field and behave differently depending on its value. For
|
||||
example, a website type component may present tooling in the Backstage interface
|
||||
@@ -304,9 +307,9 @@ The current set of well-known and common values for this field is:
|
||||
|
||||
### `spec.lifecycle` [required]
|
||||
|
||||
The lifecyle state of the component, e.g. `production`. This field is required.
|
||||
The lifecycle state of the component, e.g. `production`. This field is required.
|
||||
|
||||
The software catalog accepts any lifecycle value, but an organisation should
|
||||
The software catalog accepts any lifecycle value, but an organization should
|
||||
take great care to establish a proper taxonomy for these.
|
||||
|
||||
The current set of well-known and common values for this field is:
|
||||
@@ -418,7 +421,7 @@ potentially search and group templates by these tags.
|
||||
The type of component as a string, e.g. `website`. This field is optional but
|
||||
recommended.
|
||||
|
||||
The software catalog accepts any type value, but an organisation should take
|
||||
The software catalog accepts any type value, but an organization should take
|
||||
great care to establish a proper taxonomy for these. Tools including Backstage
|
||||
itself may read this field and behave differently depending on its value. For
|
||||
example, a website type component may present tooling in the Backstage interface
|
||||
@@ -508,7 +511,7 @@ Exactly equal to `backstage.io/v1alpha1` and `API`, respectively.
|
||||
The type of the API definition as a string, e.g. `openapi`. This field is
|
||||
required.
|
||||
|
||||
The software catalog accepts any type value, but an organisation should take
|
||||
The software catalog accepts any type value, but an organization should take
|
||||
great care to establish a proper taxonomy for these. Tools including Backstage
|
||||
itself may read this field and behave differently depending on its value. For
|
||||
example, an OpenAPI type API may be displayed using an OpenAPI viewer tooling in
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
id: software-catalog-overview
|
||||
title: Backstage Service Catalog (alpha)
|
||||
sidebar_label: Backstage Service Catalog
|
||||
sidebar_label: Overview
|
||||
---
|
||||
|
||||
## What is a Service Catalog?
|
||||
@@ -48,7 +48,7 @@ There are 3 ways to add components to the catalog:
|
||||
|
||||
1. Manually register components
|
||||
2. Creating new components through Backstage
|
||||
3. Integrating with and [external source](external-integrations.md)
|
||||
3. Integrating with an [external source](external-integrations.md)
|
||||
|
||||
### Manually register components
|
||||
|
||||
|
||||
@@ -0,0 +1,134 @@
|
||||
---
|
||||
id: well-known-annotations
|
||||
title: Well-known Annotations on Catalog Entities
|
||||
sidebar_label: Well-known Annotations
|
||||
---
|
||||
|
||||
This section lists a number of well known
|
||||
[annotations](descriptor-format.md#annotations-optional), that have defined
|
||||
semantics. They can be attached to catalog entities and consumed by plugins as
|
||||
needed.
|
||||
|
||||
## Annotations
|
||||
|
||||
This is a (non-exhaustive) list of annotations that are known to be in active
|
||||
use.
|
||||
|
||||
### backstage.io/managed-by-location
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
backstage.io/managed-by-location: github:http://github.com/spotify/backstage/catalog-info.yaml
|
||||
```
|
||||
|
||||
The value of this annotation is a so called location reference string, that
|
||||
points to the source from which the entity was originally fetched. This
|
||||
annotation is added automatically by the catalog as it fetches the data from a
|
||||
registered location, and is not meant to normally be written by humans. The
|
||||
annotation may point to any type of generic location that the catalog supports,
|
||||
so it cannot be relied on to always be specifically of type `github`, nor that
|
||||
it even represents a single file. Note also that a single location can be the
|
||||
source of many entities, so it represents a many-to-one relationship.
|
||||
|
||||
The format of the value is `<type>:<target>`. Note that the target may also
|
||||
contain colons, so it is not advisable to naively split the value on `:` and
|
||||
expecting a two-item array out of it. The format of the target part is
|
||||
type-dependent and could conceivably even be an empty string, but the separator
|
||||
colon is always present.
|
||||
|
||||
### backstage.io/techdocs-ref
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
backstage.io/techdocs-ref: github:https://github.com/spotify/backstage.git
|
||||
```
|
||||
|
||||
The value of this annotation is a location reference string (see above). If this
|
||||
annotation is specified, it is expected to point to a repository that the
|
||||
TechDocs system can read and generate docs from.
|
||||
|
||||
### backstage.io/jenkins-github-folder
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
backstage.io/jenkins-github-folder: folder-name/job-name
|
||||
```
|
||||
|
||||
The value of this annotation is the path to a job on Jenkins, that builds this
|
||||
entity.
|
||||
|
||||
Specifying this annotation may enable Jenkins related features in Backstage for
|
||||
that entity.
|
||||
|
||||
### github.com/project-slug
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
github.com/project-slug: spotify/backstage
|
||||
```
|
||||
|
||||
The value of this annotation is the so-called slug that identifies a project on
|
||||
[GitHub](https://github.com) that is related to this entity. It is on the format
|
||||
`<organization>/<project>`, and is the same as can be seen in the URL location
|
||||
bar of the browser when viewing that project.
|
||||
|
||||
Specifying this annotation will enable GitHub related features in Backstage for
|
||||
that entity.
|
||||
|
||||
### sentry.io/project-slug
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
sentry.io/project-slug: pump-station
|
||||
```
|
||||
|
||||
The value of this annotation is the so-called slug (or alternatively, the ID) of
|
||||
a [Sentry](https://sentry.io) project within your organization. The organization
|
||||
slug is currently not configurable on a per-entity basis, but is assumed to be
|
||||
the same for all entities in the catalog.
|
||||
|
||||
Specifying this annotation may enable Sentry related features in Backstage for
|
||||
that entity.
|
||||
|
||||
### rollbar.com/project-slug
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
rollbar.com/project-slug: spotify/pump-station
|
||||
```
|
||||
|
||||
The value of this annotation is the so-called slug (or alternatively, the ID) of
|
||||
a [Rollbar](https://rollbar.com) project within your organization. The value can
|
||||
be the format of `[organization]/[project-slug]` or just `[project-slug]`. When
|
||||
the organization slug is omitted the `app-config.yaml` will be used as a
|
||||
fallback (`rollbar.organization` followed by `organization.name`).
|
||||
|
||||
Specifying this annotation may enable Rollbar related features in Backstage for
|
||||
that entity.
|
||||
|
||||
## Deprecated Annotations
|
||||
|
||||
The following annotations are deprecated, and only listed here to aid in
|
||||
migrating away from them.
|
||||
|
||||
### backstage.io/github-actions-id
|
||||
|
||||
This annotation was used for a while to enable the GitHub Actions feature. This
|
||||
is now instead using the [github.com/project-slug](#github-com-project-slug)
|
||||
annotation, with the same value format.
|
||||
|
||||
## Links
|
||||
|
||||
- [Descriptor Format: annotations](descriptor-format.md#annotations-optional)
|
||||
@@ -7,18 +7,18 @@ Publishers are responsible for pushing and storing the templated skeleton after
|
||||
the values have been templated by the `Templater`. See
|
||||
[Create your own templater](./create-your-own-templater.md) for more info.
|
||||
|
||||
They receive a directory or location where the templater has sucessfully run
|
||||
and is now ready to store somewhere. They also are given some other options
|
||||
which are sent from the frontend, such as the `storePath` which is a string of
|
||||
where the frontend thinks we should save this templated folder.
|
||||
They receive a directory or location where the templater has sucessfully run and
|
||||
is now ready to store somewhere. They also are given some other options which
|
||||
are sent from the frontend, such as the `storePath` which is a string of where
|
||||
the frontend thinks we should save this templated folder.
|
||||
|
||||
Currently we provide the following `publishers`:
|
||||
|
||||
- `github`
|
||||
|
||||
This publisher is passed through to the `createRouter` function of the
|
||||
`@spotify/plugin-scaffolder-backend`. Currently, only one publisher is supported,
|
||||
but PR's are always welcome.
|
||||
`@spotify/plugin-scaffolder-backend`. Currently, only one publisher is
|
||||
supported, but PR's are always welcome.
|
||||
|
||||
An full example backend can be found
|
||||
[here](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts),
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
id: software-templates-index
|
||||
title: Software Templates
|
||||
title: Backstage Software Templates
|
||||
sidebar_label: Overview
|
||||
---
|
||||
|
||||
The Software Templates part of Backstage is a tool that can help you create
|
||||
Components inside Backstage. By default, it has the ability to load skeletons of
|
||||
Components inside Backstage. By default, it has the ability to load skeletons of
|
||||
code, template in some variables, and then publish the template to some location
|
||||
like GitHub.
|
||||
|
||||
|
||||
@@ -30,9 +30,9 @@ the documentation template.
|
||||
Create an entity from the documentation template and you will get the needed
|
||||
setup for free.
|
||||
|
||||
!!! warning Currently the Backstage Software Templates are limited to create repositories
|
||||
inside GitHub organizations. You also need to generate an personal access token
|
||||
and use as an environment variable. Read more about this
|
||||
!!! warning Currently the Backstage Software Templates are limited to create
|
||||
repositories inside GitHub organizations. You also need to generate an personal
|
||||
access token and use as an environment variable. Read more about this
|
||||
[here](../software-templates/installation.md#runtime-dependencies).
|
||||
|
||||
### Manually add documentation setup to already existing repository
|
||||
|
||||
Reference in New Issue
Block a user