Diagrams in Backstage

You can integrate Revision diagrams directly into your Backstage instances using our Backstage plugin.

Getting started

1. First, install the Revision plugin:

   # From your Backstage root directory
   yarn add --cwd packages/app @revisionapp/backstage-revision-plugin

2. Then, add the EntityRevisionContent component as an EntityLayout route on the EntityPage:

   // packages/app/src/components/catalog/EntityPage.tsx
   import { EntityRevisionContent } from "@revisionapp/backstage-revision-plugin";
   
   const serviceEntityPage = (
     <EntityLayout>
       // ...
       <EntityLayout.Route path="/revision-diagram" title="Diagram">
         <EntityRevisionContent />
       </EntityLayout.Route>
       // ...
     </EntityLayout>
   );

3. Set up the necessary configuration, including both proxy settings and your Revision base URL in your app config:

   # app-config.yaml
   proxy:
     endpoints:
       "/revision":
         target: https://<your-organization>.revision.app
         headers:
           Authorization: "Bearer ${REVISION_API_KEY}"
   revision:
     baseUrl: https://<your-organization>.revision.app

4. Add a revision.app/diagram-slug annotation to your catalog info file:

   # catalog-info.yaml
   apiVersion: backstage.io/v1alpha1
   kind: Component
   metadata:
     name: backstage
     description: |
       Backstage is an open-source developer portal that puts the developer experience first.
     annotations:
       revision.app/diagram-slug: YOUR_DIAGRAM_SLUG # e.g. TyY5fbQU9D3S
   spec:
     type: library
     owner: CNCF
     lifecycle: experimental

   This is the slug that determines which diagram should be shown. You can find it in the diagram's URL, or using the Revision API.

5. Set your Revision organization's API key, located under "Settings" > "Security" in Revision (requires administrator access), as an environmental variable called REVISION_API_KEY.