Merge branch 'master' of github.com:backstage/backstage into update-org-cards

plugins/catalog-backend/src/ingestion/HigherOrderOperations.ts

@@ -130,7 +130,7 @@ export class HigherOrderOperations implements HigherOrderOperation {
         `Locations Refresh: Refreshing location ${location.type}:${location.target}`,
       );
       try {
-        await this.refreshSingleLocation(location);
+        await this.refreshSingleLocation(location, logger);
         await this.locationsCatalog.logUpdateSuccess(location.id, undefined);
       } catch (e) {
         logger.warn(
@@ -148,8 +148,12 @@ export class HigherOrderOperations implements HigherOrderOperation {
   }
 
   // Performs a full refresh of a single location
-  private async refreshSingleLocation(location: Location) {
+  private async refreshSingleLocation(
+    location: Location,
+    optionalLogger?: Logger,
+  ) {
     let startTimestamp = process.hrtime();
+    const logger = optionalLogger || this.logger;
 
     const readerOutput = await this.locationReader.read({
       type: location.type,
@@ -157,12 +161,12 @@ export class HigherOrderOperations implements HigherOrderOperation {
     });
 
     for (const item of readerOutput.errors) {
-      this.logger.warn(
+      logger.warn(
         `Failed item in location ${item.location.type}:${item.location.target}, ${item.error.stack}`,
       );
     }
 
-    this.logger.info(
+    logger.info(
       `Read ${readerOutput.entities.length} entities from location ${
         location.type
       }:${location.target} in ${durationText(startTimestamp)}`,
@@ -186,14 +190,14 @@ export class HigherOrderOperations implements HigherOrderOperation {
       throw e;
     }
 
-    this.logger.debug(`Posting update success markers`);
+    logger.debug(`Posting update success markers`);
 
     await this.locationsCatalog.logUpdateSuccess(
       location.id,
       readerOutput.entities.map(e => e.entity.metadata.name),
     );
 
-    this.logger.info(
+    logger.info(
       `Wrote ${readerOutput.entities.length} entities from location ${
         location.type
       }:${location.target} in ${durationText(startTimestamp)}`,

plugins/catalog-backend/src/service/router.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { errorHandler } from '@backstage/backend-common';
+import { errorHandler, NotFoundError } from '@backstage/backend-common';
 import {
   locationSpecSchema,
   analyzeLocationSchema,
@@ -57,7 +57,7 @@ export async function createRouter(
         const filter = EntityFilters.ofQuery(req.query);
         const fieldMapper = translateQueryToFieldMapper(req.query);
         const entities = await entitiesCatalog.entities(filter);
-        res.status(200).send(entities.map(fieldMapper));
+        res.status(200).json(entities.map(fieldMapper));
       })
       .post('/entities', async (req, res) => {
         const body = await requireRequestBody(req);
@@ -67,7 +67,7 @@ export async function createRouter(
         const [entity] = await entitiesCatalog.entities(
           EntityFilters.ofMatchers({ 'metadata.uid': result.entityId }),
         );
-        res.status(200).send(entity);
+        res.status(200).json(entity);
       })
       .get('/entities/by-uid/:uid', async (req, res) => {
         const { uid } = req.params;
@@ -75,14 +75,14 @@ export async function createRouter(
           EntityFilters.ofMatchers({ 'metadata.uid': uid }),
         );
         if (!entities.length) {
-          res.status(404).send(`No entity with uid ${uid}`);
+          throw new NotFoundError(`No entity with uid ${uid}`);
         }
-        res.status(200).send(entities[0]);
+        res.status(200).json(entities[0]);
       })
       .delete('/entities/by-uid/:uid', async (req, res) => {
         const { uid } = req.params;
         await entitiesCatalog.removeEntityByUid(uid);
-        res.status(204).send();
+        res.status(204).end();
       })
       .get('/entities/by-name/:kind/:namespace/:name', async (req, res) => {
         const { kind, namespace, name } = req.params;
@@ -94,13 +94,11 @@ export async function createRouter(
           }),
         );
         if (!entities.length) {
-          res
-            .status(404)
-            .send(
-              `No entity with kind ${kind} namespace ${namespace} name ${name}`,
-            );
+          throw new NotFoundError(
+            `No entity with kind ${kind} namespace ${namespace} name ${name}`,
+          );
         }
-        res.status(200).send(entities[0]);
+        res.status(200).json(entities[0]);
       });
   }
 
@@ -109,7 +107,7 @@ export async function createRouter(
       const input = await validateRequestBody(req, locationSpecSchema);
       const dryRun = yn(req.query.dryRun, { default: false });
       const output = await higherOrderOperation.addLocation(input, { dryRun });
-      res.status(201).send(output);
+      res.status(201).json(output);
     });
   }
 
@@ -117,22 +115,22 @@ export async function createRouter(
     router
       .get('/locations', async (_req, res) => {
         const output = await locationsCatalog.locations();
-        res.status(200).send(output);
+        res.status(200).json(output);
       })
       .get('/locations/:id/history', async (req, res) => {
         const { id } = req.params;
         const output = await locationsCatalog.locationHistory(id);
-        res.status(200).send(output);
+        res.status(200).json(output);
       })
       .get('/locations/:id', async (req, res) => {
         const { id } = req.params;
         const output = await locationsCatalog.location(id);
-        res.status(200).send(output);
+        res.status(200).json(output);
       })
       .delete('/locations/:id', async (req, res) => {
         const { id } = req.params;
         await locationsCatalog.removeLocation(id);
-        res.status(204).send();
+        res.status(204).end();
       });
   }
 
@@ -140,7 +138,7 @@ export async function createRouter(
     router.post('/analyze-location', async (req, res) => {
       const input = await validateRequestBody(req, analyzeLocationSchema);
       const output = await locationAnalyzer.analyzeLocation(input);
-      res.status(200).send(output);
+      res.status(200).json(output);
     });
   }
 

plugins/circleci/dev/index.tsx

@@ -15,6 +15,6 @@
  */
 
 import { createDevApp } from '@backstage/dev-utils';
-import { plugin } from '../src/plugin';
+import { circleCIPlugin } from '../src/plugin';
 
-createDevApp().registerPlugin(plugin).render();
+createDevApp().registerPlugin(circleCIPlugin).render();

plugins/circleci/src/components/Router.tsx

@@ -21,15 +21,25 @@ import { BuildWithStepsPage } from './BuildWithStepsPage/';
 import { BuildsPage } from './BuildsPage';
 import { CIRCLECI_ANNOTATION } from '../constants';
 import { Entity } from '@backstage/catalog-model';
+import { useEntity } from '@backstage/plugin-catalog-react';
 import { MissingAnnotationEmptyState } from '@backstage/core';
 
-export const isPluginApplicableToEntity = (entity: Entity) =>
+export const isCircleCIAvailable = (entity: Entity) =>
   Boolean(entity.metadata.annotations?.[CIRCLECI_ANNOTATION]);
 
-export const Router = ({ entity }: { entity: Entity }) =>
-  !isPluginApplicableToEntity(entity) ? (
-    <MissingAnnotationEmptyState annotation={CIRCLECI_ANNOTATION} />
-  ) : (
+type Props = {
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
+};
+
+export const Router = (_props: Props) => {
+  const { entity } = useEntity();
+
+  if (!isCircleCIAvailable(entity)) {
+    return <MissingAnnotationEmptyState annotation={CIRCLECI_ANNOTATION} />;
+  }
+
+  return (
     <Routes>
       <Route path={`/${circleCIRouteRef.path}`} element={<BuildsPage />} />
       <Route
@@ -38,3 +48,4 @@ export const Router = ({ entity }: { entity: Entity }) =>
       />
     </Routes>
   );
+};

plugins/circleci/src/index.ts

@@ -14,8 +14,16 @@
  * limitations under the License.
  */
 
-export { plugin } from './plugin';
+export {
+  circleCIPlugin,
+  circleCIPlugin as plugin,
+  EntityCircleCIContent,
+} from './plugin';
 export * from './api';
 export * from './route-refs';
-export { Router, isPluginApplicableToEntity } from './components/Router';
+export {
+  Router,
+  isCircleCIAvailable,
+  isCircleCIAvailable as isPluginApplicableToEntity,
+} from './components/Router';
 export { CIRCLECI_ANNOTATION } from './constants';

plugins/circleci/src/plugin.test.ts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 
-import { plugin } from './plugin';
+import { circleCIPlugin } from './plugin';
 
 describe('circleci', () => {
   it('should export plugin', () => {
-    expect(plugin).toBeDefined();
+    expect(circleCIPlugin).toBeDefined();
   });
 });

plugins/circleci/src/plugin.ts

@@ -18,10 +18,12 @@ import {
   createPlugin,
   createApiFactory,
   discoveryApiRef,
+  createRoutableExtension,
 } from '@backstage/core';
 import { circleCIApiRef, CircleCIApi } from './api';
+import { circleCIRouteRef } from './route-refs';
 
-export const plugin = createPlugin({
+export const circleCIPlugin = createPlugin({
   id: 'circleci',
   apis: [
     createApiFactory({
@@ -31,3 +33,10 @@ export const plugin = createPlugin({
     }),
   ],
 });
+
+export const EntityCircleCIContent = circleCIPlugin.provide(
+  createRoutableExtension({
+    component: () => import('./components/Router').then(m => m.Router),
+    mountPoint: circleCIRouteRef,
+  }),
+);

plugins/cloudbuild/dev/index.tsx

@@ -14,6 +14,6 @@
  * limitations under the License.
  */
 import { createDevApp } from '@backstage/dev-utils';
-import { plugin } from '../src/plugin';
+import { cloudbuildPlugin } from '../src/plugin';
 
-createDevApp().registerPlugin(plugin).render();
+createDevApp().registerPlugin(cloudbuildPlugin).render();

plugins/cloudbuild/package.json

@@ -31,6 +31,7 @@
   },
   "dependencies": {
     "@backstage/catalog-model": "^0.7.1",
+    "@backstage/plugin-catalog-react": "^0.0.2",
     "@backstage/core": "^0.6.0",
     "@backstage/theme": "^0.2.3",
     "@material-ui/core": "^4.11.0",

plugins/cloudbuild/src/components/Cards/Cards.tsx

@@ -17,6 +17,7 @@ import React, { useEffect } from 'react';
 import { useWorkflowRuns } from '../useWorkflowRuns';
 import { WorkflowRun, WorkflowRunsTable } from '../WorkflowRunsTable';
 import { Entity } from '@backstage/catalog-model';
+import { useEntity } from '@backstage/plugin-catalog-react';
 import { WorkflowRunStatus } from '../WorkflowRunStatus';
 import { Link, Theme, makeStyles, LinearProgress } from '@material-ui/core';
 import {
@@ -72,12 +73,13 @@ const WidgetContent = ({
 };
 
 export const LatestWorkflowRunCard = ({
-  entity,
   branch = 'master',
 }: {
-  entity: Entity;
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
   branch: string;
 }) => {
+  const { entity } = useEntity();
   const errorApi = useApi(errorApiRef);
   const projectId = entity?.metadata.annotations?.[CLOUDBUILD_ANNOTATION] || '';
 
@@ -104,13 +106,17 @@ export const LatestWorkflowRunCard = ({
 };
 
 export const LatestWorkflowsForBranchCard = ({
-  entity,
   branch = 'master',
 }: {
-  entity: Entity;
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
   branch: string;
-}) => (
-  <InfoCard title={`Last ${branch} build`}>
-    <WorkflowRunsTable entity={entity} />
-  </InfoCard>
-);
+}) => {
+  const { entity } = useEntity();
+
+  return (
+    <InfoCard title={`Last ${branch} build`}>
+      <WorkflowRunsTable entity={entity} />
+    </InfoCard>
+  );
+};

plugins/cloudbuild/src/components/Router.tsx

@@ -15,6 +15,7 @@
  */
 import React from 'react';
 import { Entity } from '@backstage/catalog-model';
+import { useEntity } from '@backstage/plugin-catalog-react';
 import { Routes, Route } from 'react-router';
 import { rootRouteRef, buildRouteRef } from '../plugin';
 import { WorkflowRunDetails } from './WorkflowRunDetails';
@@ -22,14 +23,22 @@ import { WorkflowRunsTable } from './WorkflowRunsTable';
 import { CLOUDBUILD_ANNOTATION } from './useProjectName';
 import { MissingAnnotationEmptyState } from '@backstage/core';
 
-export const isPluginApplicableToEntity = (entity: Entity) =>
+export const isCloudbuildAvailable = (entity: Entity) =>
   Boolean(entity.metadata.annotations?.[CLOUDBUILD_ANNOTATION]);
 
-export const Router = ({ entity }: { entity: Entity }) =>
-  // TODO(shmidt-i): move warning to a separate standardized component
-  !isPluginApplicableToEntity(entity) ? (
-    <MissingAnnotationEmptyState annotation={CLOUDBUILD_ANNOTATION} />
-  ) : (
+type Props = {
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
+};
+
+export const Router = (_props: Props) => {
+  const { entity } = useEntity();
+
+  if (!isCloudbuildAvailable(entity)) {
+    // TODO(shmidt-i): move warning to a separate standardized component
+    return <MissingAnnotationEmptyState annotation={CLOUDBUILD_ANNOTATION} />;
+  }
+  return (
     <Routes>
       <Route
         path={`/${rootRouteRef.path}`}
@@ -42,3 +51,4 @@ export const Router = ({ entity }: { entity: Entity }) =>
       )
     </Routes>
   );
+};

plugins/cloudbuild/src/index.ts

@@ -13,8 +13,18 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export { plugin } from './plugin';
+export {
+  cloudbuildPlugin,
+  cloudbuildPlugin as plugin,
+  EntityCloudbuildContent,
+  EntityLatestCloudbuildRunCard,
+  EntityLatestCloudbuildsForBranchCard,
+} from './plugin';
 export * from './api';
-export { Router, isPluginApplicableToEntity } from './components/Router';
+export {
+  Router,
+  isCloudbuildAvailable,
+  isCloudbuildAvailable as isPluginApplicableToEntity,
+} from './components/Router';
 export * from './components/Cards';
 export { CLOUDBUILD_ANNOTATION } from './components/useProjectName';

plugins/cloudbuild/src/plugin.test.ts

@@ -13,10 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { plugin } from './plugin';
+import { cloudbuildPlugin } from './plugin';
 
 describe('cloudbuild', () => {
   it('should export plugin', () => {
-    expect(plugin).toBeDefined();
+    expect(cloudbuildPlugin).toBeDefined();
   });
 });

plugins/cloudbuild/src/plugin.ts

@@ -18,6 +18,8 @@ import {
   createRouteRef,
   createApiFactory,
   googleAuthApiRef,
+  createRoutableExtension,
+  createComponentExtension,
 } from '@backstage/core';
 import { cloudbuildApiRef, CloudbuildClient } from './api';
 
@@ -31,7 +33,7 @@ export const buildRouteRef = createRouteRef({
   title: 'Cloudbuild Run',
 });
 
-export const plugin = createPlugin({
+export const cloudbuildPlugin = createPlugin({
   id: 'cloudbuild',
   apis: [
     createApiFactory({
@@ -42,4 +44,32 @@ export const plugin = createPlugin({
       },
     }),
   ],
+  routes: {
+    entityContent: rootRouteRef,
+  },
 });
+
+export const EntityCloudbuildContent = cloudbuildPlugin.provide(
+  createRoutableExtension({
+    component: () => import('./components/Router').then(m => m.Router),
+    mountPoint: rootRouteRef,
+  }),
+);
+
+export const EntityLatestCloudbuildRunCard = cloudbuildPlugin.provide(
+  createComponentExtension({
+    component: {
+      lazy: () =>
+        import('./components/Cards').then(m => m.LatestWorkflowRunCard),
+    },
+  }),
+);
+
+export const EntityLatestCloudbuildsForBranchCard = cloudbuildPlugin.provide(
+  createComponentExtension({
+    component: {
+      lazy: () =>
+        import('./components/Cards').then(m => m.LatestWorkflowsForBranchCard),
+    },
+  }),
+);

plugins/cost-insights/src/types/Alert.ts

@@ -149,7 +149,7 @@ export const AlertSnoozeOptions: AlertSnoozeOption[] = [
     label: '1 Month',
   },
   {
-    duration: Duration.P3M,
+    duration: Duration.P90D,
     label: '1 Quarter',
   },
 ];

plugins/github-actions/dev/index.tsx

@@ -15,6 +15,6 @@
  */
 
 import { createDevApp } from '@backstage/dev-utils';
-import { plugin } from '../src/plugin';
+import { githubActionsPlugin } from '../src/plugin';
 
-createDevApp().registerPlugin(plugin).render();
+createDevApp().registerPlugin(githubActionsPlugin).render();

plugins/github-actions/package.json

@@ -33,6 +33,7 @@
   },
   "dependencies": {
     "@backstage/catalog-model": "^0.7.1",
+    "@backstage/plugin-catalog-react": "^0.0.2",
     "@backstage/core": "^0.6.0",
     "@backstage/integration": "^0.3.2",
     "@backstage/theme": "^0.2.3",

plugins/github-actions/src/components/Cards/Cards.tsx

@@ -17,6 +17,7 @@ import React, { useEffect } from 'react';
 import { useWorkflowRuns } from '../useWorkflowRuns';
 import { WorkflowRun, WorkflowRunsTable } from '../WorkflowRunsTable';
 import { Entity } from '@backstage/catalog-model';
+import { useEntity } from '@backstage/plugin-catalog-react';
 import { readGitHubIntegrationConfigs } from '@backstage/integration';
 import { WorkflowRunStatus } from '../WorkflowRunStatus';
 import {
@@ -81,11 +82,11 @@ const WidgetContent = ({
 };
 
 export const LatestWorkflowRunCard = ({
-  entity,
   branch = 'master',
   // Display the card full height suitable for
   variant,
 }: Props) => {
+  const { entity } = useEntity();
   const config = useApi(configApiRef);
   const errorApi = useApi(errorApiRef);
   // TODO: Get github hostname from metadata annotation
@@ -121,17 +122,21 @@ export const LatestWorkflowRunCard = ({
 };
 
 type Props = {
-  entity: Entity;
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
   branch: string;
   variant?: string;
 };
 
 export const LatestWorkflowsForBranchCard = ({
-  entity,
   branch = 'master',
   variant,
-}: Props) => (
-  <InfoCard title={`Last ${branch} build`} variant={variant}>
-    <WorkflowRunsTable branch={branch} entity={entity} />
-  </InfoCard>
-);
+}: Props) => {
+  const { entity } = useEntity();
+
+  return (
+    <InfoCard title={`Last ${branch} build`} variant={variant}>
+      <WorkflowRunsTable branch={branch} entity={entity} />
+    </InfoCard>
+  );
+};

plugins/github-actions/src/components/Cards/RecentWorkflowRunsCard.test.tsx

@@ -22,6 +22,7 @@ import {
   ConfigApi,
   ConfigReader,
 } from '@backstage/core';
+import { EntityProvider } from '@backstage/plugin-catalog-react';
 import { lightTheme } from '@backstage/theme';
 import { ThemeProvider } from '@material-ui/core';
 import { render } from '@testing-library/react';
@@ -84,7 +85,9 @@ describe('<RecentWorkflowRunsCard />', () => {
               configApi,
             )}
           >
-            <RecentWorkflowRunsCard {...props} />
+            <EntityProvider entity={props.entity!}>
+              <RecentWorkflowRunsCard {...props} />
+            </EntityProvider>
           </ApiProvider>
         </MemoryRouter>
       </ThemeProvider>,

plugins/github-actions/src/components/Cards/RecentWorkflowRunsCard.tsx

@@ -23,6 +23,7 @@ import {
   useApi,
 } from '@backstage/core';
 import { readGitHubIntegrationConfigs } from '@backstage/integration';
+import { useEntity } from '@backstage/plugin-catalog-react';
 import { Button, Link } from '@material-ui/core';
 import React, { useEffect } from 'react';
 import { generatePath, Link as RouterLink } from 'react-router-dom';
@@ -33,7 +34,8 @@ import { WorkflowRunStatus } from '../WorkflowRunStatus';
 const firstLine = (message: string): string => message.split('\n')[0];
 
 export type Props = {
-  entity: Entity;
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
   branch?: string;
   dense?: boolean;
   limit?: number;
@@ -41,12 +43,12 @@ export type Props = {
 };
 
 export const RecentWorkflowRunsCard = ({
-  entity,
   branch,
   dense = false,
   limit = 5,
   variant,
 }: Props) => {
+  const { entity } = useEntity();
   const config = useApi(configApiRef);
   const errorApi = useApi(errorApiRef);
   // TODO: Get github hostname from metadata annotation

plugins/github-actions/src/components/Router.tsx

@@ -15,6 +15,7 @@
  */
 import React from 'react';
 import { Entity } from '@backstage/catalog-model';
+import { useEntity } from '@backstage/plugin-catalog-react';
 import { Routes, Route } from 'react-router';
 import { rootRouteRef, buildRouteRef } from '../plugin';
 import { WorkflowRunDetails } from './WorkflowRunDetails';
@@ -22,13 +23,23 @@ import { WorkflowRunsTable } from './WorkflowRunsTable';
 import { GITHUB_ACTIONS_ANNOTATION } from './useProjectName';
 import { MissingAnnotationEmptyState } from '@backstage/core';
 
-export const isPluginApplicableToEntity = (entity: Entity) =>
+export const isGithubActionsAvailable = (entity: Entity) =>
   Boolean(entity.metadata.annotations?.[GITHUB_ACTIONS_ANNOTATION]);
 
-export const Router = ({ entity }: { entity: Entity }) =>
-  !isPluginApplicableToEntity(entity) ? (
-    <MissingAnnotationEmptyState annotation={GITHUB_ACTIONS_ANNOTATION} />
-  ) : (
+type Props = {
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
+};
+
+export const Router = (_props: Props) => {
+  const { entity } = useEntity();
+
+  if (!isGithubActionsAvailable(entity)) {
+    return (
+      <MissingAnnotationEmptyState annotation={GITHUB_ACTIONS_ANNOTATION} />
+    );
+  }
+  return (
     <Routes>
       <Route
         path={`/${rootRouteRef.path}`}
@@ -41,3 +52,4 @@ export const Router = ({ entity }: { entity: Entity }) =>
       )
     </Routes>
   );
+};

plugins/github-actions/src/index.ts

@@ -14,8 +14,19 @@
  * limitations under the License.
  */
 
-export { plugin } from './plugin';
+export {
+  githubActionsPlugin,
+  githubActionsPlugin as plugin,
+  EntityGithubActionsContent,
+  EntityLatestGithubActionRunCard,
+  EntityLatestGithubActionsForBranchCard,
+  EntityRecentGithubActionsRunsCard,
+} from './plugin';
 export * from './api';
-export { Router, isPluginApplicableToEntity } from './components/Router';
+export {
+  Router,
+  isGithubActionsAvailable,
+  isGithubActionsAvailable as isPluginApplicableToEntity,
+} from './components/Router';
 export * from './components/Cards';
 export { GITHUB_ACTIONS_ANNOTATION } from './components/useProjectName';

plugins/github-actions/src/plugin.test.ts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 
-import { plugin } from './plugin';
+import { githubActionsPlugin } from './plugin';
 
 describe('github-actions', () => {
   it('should export plugin', () => {
-    expect(plugin).toBeDefined();
+    expect(githubActionsPlugin).toBeDefined();
   });
 });

plugins/github-actions/src/plugin.ts

@@ -20,6 +20,8 @@ import {
   createRouteRef,
   createApiFactory,
   githubAuthApiRef,
+  createRoutableExtension,
+  createComponentExtension,
 } from '@backstage/core';
 import { githubActionsApiRef, GithubActionsClient } from './api';
 
@@ -34,7 +36,7 @@ export const buildRouteRef = createRouteRef({
   title: 'GitHub Actions Workflow Run',
 });
 
-export const plugin = createPlugin({
+export const githubActionsPlugin = createPlugin({
   id: 'github-actions',
   apis: [
     createApiFactory({
@@ -44,4 +46,41 @@ export const plugin = createPlugin({
         new GithubActionsClient({ configApi, githubAuthApi }),
     }),
   ],
+  routes: {
+    entityContent: rootRouteRef,
+  },
 });
+
+export const EntityGithubActionsContent = githubActionsPlugin.provide(
+  createRoutableExtension({
+    component: () => import('./components/Router').then(m => m.Router),
+    mountPoint: rootRouteRef,
+  }),
+);
+
+export const EntityLatestGithubActionRunCard = githubActionsPlugin.provide(
+  createComponentExtension({
+    component: {
+      lazy: () =>
+        import('./components/Cards').then(m => m.LatestWorkflowRunCard),
+    },
+  }),
+);
+
+export const EntityLatestGithubActionsForBranchCard = githubActionsPlugin.provide(
+  createComponentExtension({
+    component: {
+      lazy: () =>
+        import('./components/Cards').then(m => m.LatestWorkflowsForBranchCard),
+    },
+  }),
+);
+
+export const EntityRecentGithubActionsRunsCard = githubActionsPlugin.provide(
+  createComponentExtension({
+    component: {
+      lazy: () =>
+        import('./components/Cards').then(m => m.RecentWorkflowRunsCard),
+    },
+  }),
+);

plugins/gitops-profiles/dev/index.tsx

@@ -15,6 +15,6 @@
  */
 
 import { createDevApp } from '@backstage/dev-utils';
-import { plugin } from '../src/plugin';
+import { gitopsProfilesPlugin } from '../src/plugin';
 
-createDevApp().registerPlugin(plugin).render();
+createDevApp().registerPlugin(gitopsProfilesPlugin).render();

plugins/gitops-profiles/src/index.ts

@@ -14,5 +14,11 @@
  * limitations under the License.
  */
 
-export { plugin } from './plugin';
+export {
+  gitopsProfilesPlugin,
+  gitopsProfilesPlugin as plugin,
+  GitopsProfilesClusterListPage,
+  GitopsProfilesClusterPage,
+  GitopsProfilesCreatePage,
+} from './plugin';
 export * from './api';

plugins/gitops-profiles/src/plugin.test.ts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 
-import { plugin } from './plugin';
+import { gitopsProfilesPlugin } from './plugin';
 
 describe('gitops-profiles', () => {
   it('should export plugin', () => {
-    expect(plugin).toBeDefined();
+    expect(gitopsProfilesPlugin).toBeDefined();
   });
 });

plugins/gitops-profiles/src/plugin.ts

@@ -14,7 +14,11 @@
  * limitations under the License.
  */
 
-import { createPlugin, createApiFactory } from '@backstage/core';
+import {
+  createPlugin,
+  createApiFactory,
+  createRoutableExtension,
+} from '@backstage/core';
 import ProfileCatalog from './components/ProfileCatalog';
 import ClusterPage from './components/ClusterPage';
 import ClusterList from './components/ClusterList';
@@ -25,7 +29,7 @@ import {
 } from './routes';
 import { gitOpsApiRef, GitOpsRestApi } from './api';
 
-export const plugin = createPlugin({
+export const gitopsProfilesPlugin = createPlugin({
   id: 'gitops-profiles',
   apis: [
     createApiFactory(gitOpsApiRef, new GitOpsRestApi('http://localhost:3008')),
@@ -35,4 +39,30 @@ export const plugin = createPlugin({
     router.addRoute(gitOpsClusterDetailsRoute, ClusterPage);
     router.addRoute(gitOpsClusterCreateRoute, ProfileCatalog);
   },
+  routes: {
+    listPage: gitOpsClusterListRoute,
+    detailsPage: gitOpsClusterDetailsRoute,
+    createPage: gitOpsClusterCreateRoute,
+  },
 });
+
+export const GitopsProfilesClusterListPage = gitopsProfilesPlugin.provide(
+  createRoutableExtension({
+    component: () => import('./components/ClusterList').then(m => m.default),
+    mountPoint: gitOpsClusterListRoute,
+  }),
+);
+
+export const GitopsProfilesClusterPage = gitopsProfilesPlugin.provide(
+  createRoutableExtension({
+    component: () => import('./components/ClusterPage').then(m => m.default),
+    mountPoint: gitOpsClusterDetailsRoute,
+  }),
+);
+
+export const GitopsProfilesCreatePage = gitopsProfilesPlugin.provide(
+  createRoutableExtension({
+    component: () => import('./components/ProfileCatalog').then(m => m.default),
+    mountPoint: gitOpsClusterCreateRoute,
+  }),
+);

plugins/gitops-profiles/src/routes.ts

@@ -28,6 +28,7 @@ export const gitOpsClusterDetailsRoute = createRouteRef({
   icon: NoIcon,
   path: '/gitops-cluster/:owner/:repo',
   title: 'GitOps Cluster details',
+  params: ['owner', 'repo'],
 });
 
 export const gitOpsClusterCreateRoute = createRouteRef({

plugins/jenkins/dev/index.tsx

@@ -15,6 +15,6 @@
  */
 
 import { createDevApp } from '@backstage/dev-utils';
-import { plugin } from '../src/plugin';
+import { jenkinsPlugin } from '../src/plugin';
 
-createDevApp().registerPlugin(plugin).render();
+createDevApp().registerPlugin(jenkinsPlugin).render();

plugins/jenkins/src/components/Router.tsx

@@ -15,6 +15,7 @@
  */
 import React from 'react';
 import { Route, Routes } from 'react-router';
+import { useEntity } from '@backstage/plugin-catalog-react';
 import { buildRouteRef, rootRouteRef } from '../plugin';
 import { DetailedViewPage } from './BuildWithStepsPage/';
 import { JENKINS_ANNOTATION } from '../constants';
@@ -22,13 +23,22 @@ import { Entity } from '@backstage/catalog-model';
 import { MissingAnnotationEmptyState } from '@backstage/core';
 import { CITable } from './BuildsPage/lib/CITable';
 
-export const isPluginApplicableToEntity = (entity: Entity) =>
+export const isJenkinsAvailable = (entity: Entity) =>
   Boolean(entity.metadata.annotations?.[JENKINS_ANNOTATION]);
 
-export const Router = ({ entity }: { entity: Entity }) => {
-  return !isPluginApplicableToEntity(entity) ? (
-    <MissingAnnotationEmptyState annotation={JENKINS_ANNOTATION} />
-  ) : (
+type Props = {
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
+};
+
+export const Router = (_props: Props) => {
+  const { entity } = useEntity();
+
+  if (!isJenkinsAvailable(entity)) {
+    return <MissingAnnotationEmptyState annotation={JENKINS_ANNOTATION} />;
+  }
+
+  return (
     <Routes>
       <Route path={`/${rootRouteRef.path}`} element={<CITable />} />
       <Route path={`/${buildRouteRef.path}`} element={<DetailedViewPage />} />

plugins/jenkins/src/index.ts

@@ -14,8 +14,17 @@
  * limitations under the License.
  */
 
-export { plugin } from './plugin';
+export {
+  jenkinsPlugin,
+  jenkinsPlugin as plugin,
+  EntityJenkinsContent,
+  EntityLatestJenkinsRunCard,
+} from './plugin';
 export { LatestRunCard } from './components/Cards';
-export { Router, isPluginApplicableToEntity } from './components/Router';
+export {
+  Router,
+  isJenkinsAvailable,
+  isJenkinsAvailable as isPluginApplicableToEntity,
+} from './components/Router';
 export { JENKINS_ANNOTATION } from './constants';
 export * from './api';

plugins/jenkins/src/plugin.test.ts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 
-import { plugin } from './plugin';
+import { jenkinsPlugin } from './plugin';
 
 describe('jenkins', () => {
   it('should export plugin', () => {
-    expect(plugin).toBeDefined();
+    expect(jenkinsPlugin).toBeDefined();
   });
 });

plugins/jenkins/src/plugin.ts

@@ -19,6 +19,8 @@ import {
   createRouteRef,
   createApiFactory,
   discoveryApiRef,
+  createRoutableExtension,
+  createComponentExtension,
 } from '@backstage/core';
 import { jenkinsApiRef, JenkinsApi } from './api';
 
@@ -32,7 +34,7 @@ export const buildRouteRef = createRouteRef({
   title: 'Jenkins run',
 });
 
-export const plugin = createPlugin({
+export const jenkinsPlugin = createPlugin({
   id: 'jenkins',
   apis: [
     createApiFactory({
@@ -41,4 +43,21 @@ export const plugin = createPlugin({
       factory: ({ discoveryApi }) => new JenkinsApi({ discoveryApi }),
     }),
   ],
+  routes: {
+    entityContent: rootRouteRef,
+  },
 });
+
+export const EntityJenkinsContent = jenkinsPlugin.provide(
+  createRoutableExtension({
+    component: () => import('./components/Router').then(m => m.Router),
+    mountPoint: rootRouteRef,
+  }),
+);
+export const EntityLatestJenkinsRunCard = jenkinsPlugin.provide(
+  createComponentExtension({
+    component: {
+      lazy: () => import('./components/Cards').then(m => m.LatestRunCard),
+    },
+  }),
+);

plugins/lighthouse/src/Router.tsx

@@ -16,6 +16,7 @@
 
 import React from 'react';
 import { Route, Routes } from 'react-router-dom';
+import { useEntity } from '@backstage/plugin-catalog-react';
 import AuditList from './components/AuditList';
 import AuditView, { AuditViewContent } from './components/AuditView';
 import CreateAudit, { CreateAuditContent } from './components/CreateAudit';
@@ -35,15 +36,27 @@ export const Router = () => (
   </Routes>
 );
 
-export const EmbeddedRouter = ({ entity }: { entity: Entity }) =>
-  !isLighthouseAvailable(entity) ? (
-    <MissingAnnotationEmptyState
-      annotation={LIGHTHOUSE_WEBSITE_URL_ANNOTATION}
-    />
-  ) : (
+type Props = {
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
+};
+
+export const EmbeddedRouter = (_props: Props) => {
+  const { entity } = useEntity();
+
+  if (!isLighthouseAvailable(entity)) {
+    return (
+      <MissingAnnotationEmptyState
+        annotation={LIGHTHOUSE_WEBSITE_URL_ANNOTATION}
+      />
+    );
+  }
+
+  return (
     <Routes>
       <Route path="/" element={<AuditListForEntity />} />
       <Route path="/audit/:id" element={<AuditViewContent />} />
       <Route path="/create-audit" element={<CreateAuditContent />} />
     </Routes>
   );
+};

plugins/org/src/components/Cards/Group/GroupProfile/GroupProfileCard.tsx

@@ -24,6 +24,7 @@ import { Avatar, InfoCard } from '@backstage/core';
 import {
   getEntityRelations,
   entityRouteParams,
+  useEntity,
 } from '@backstage/plugin-catalog-react';
 import {
   Box,
@@ -45,26 +46,29 @@ import { generatePath, Link as RouterLink } from 'react-router-dom';
 const GroupLink = ({
   groupName,
   index = 0,
-  entity,
 }: {
   groupName: string;
   index?: number;
-  entity: Entity;
-}) => (
-  <>
-    {index >= 1 ? ', ' : ''}
-    <Link
-      component={RouterLink}
-      to={generatePath(
-        `/catalog/:namespace/group/${groupName}`,
-        entityRouteParams(entity),
-      )}
-    >
-      [{groupName}]
-    </Link>
-  </>
-);
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
+}) => {
+  const { entity } = useEntity();
 
+  return (
+    <>
+      {index >= 1 ? ', ' : ''}
+      <Link
+        component={RouterLink}
+        to={generatePath(
+          `/catalog/:namespace/group/${groupName}`,
+          entityRouteParams(entity),
+        )}
+      >
+        [{groupName}]
+      </Link>
+    </>
+  );
+};
 const CardTitle = ({ title }: { title: string }) => (
   <Box display="flex" alignItems="center">
     <GroupIcon fontSize="inherit" />
@@ -73,12 +77,13 @@ const CardTitle = ({ title }: { title: string }) => (
 );
 
 export const GroupProfileCard = ({
-  entity: group,
   variant,
 }: {
-  entity: GroupEntity;
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: GroupEntity;
   variant: string;
 }) => {
+  const group = useEntity().entity as GroupEntity;
   const {
     metadata: { name, description },
     spec: { profile },

plugins/org/src/components/Cards/Group/MembersList/MembersListCard.test.tsx

@@ -16,7 +16,11 @@
 
 import { Entity, GroupEntity } from '@backstage/catalog-model';
 import { ApiProvider, ApiRegistry } from '@backstage/core';
-import { CatalogApi, catalogApiRef } from '@backstage/plugin-catalog-react';
+import {
+  CatalogApi,
+  catalogApiRef,
+  EntityProvider,
+} from '@backstage/plugin-catalog-react';
 import { renderWithEffects, wrapInTestApp } from '@backstage/test-utils';
 import React from 'react';
 import { MembersListCard } from './MembersListCard';
@@ -78,7 +82,10 @@ describe('MemberTab Test', () => {
     const rendered = await renderWithEffects(
       wrapInTestApp(
         <ApiProvider apis={apis}>
-          <MembersListCard entity={groupEntity} />
+          <EntityProvider entity={groupEntity}>
+            <MembersListCard />
+          </EntityProvider>
+          ,
         </ApiProvider>,
       ),
     );

plugins/org/src/components/Cards/Group/MembersList/MembersListCard.tsx

@@ -21,6 +21,7 @@ import {
 } from '@backstage/catalog-model';
 import { Avatar, InfoCard, Progress, useApi } from '@backstage/core';
 import {
+  useEntity,
   catalogApiRef,
   entityRouteParams,
 } from '@backstage/plugin-catalog-react';
@@ -105,11 +106,11 @@ const MemberComponent = ({
   );
 };
 
-export const MembersListCard = ({
-  entity: groupEntity,
-}: {
-  entity: GroupEntity;
+export const MembersListCard = (_props: {
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: GroupEntity;
 }) => {
+  const groupEntity = useEntity().entity as GroupEntity;
   const {
     metadata: { name: groupName },
     spec: { profile },

plugins/org/src/components/Cards/OwnershipCard/OwnershipCard.tsx

@@ -16,7 +16,11 @@
 
 import { Entity } from '@backstage/catalog-model';
 import { InfoCard, Progress, useApi } from '@backstage/core';
-import { catalogApiRef, isOwnerOf } from '@backstage/plugin-catalog-react';
+import {
+  catalogApiRef,
+  isOwnerOf,
+  useEntity,
+} from '@backstage/plugin-catalog-react';
 import { pageTheme } from '@backstage/theme';
 import {
   Box,
@@ -113,12 +117,13 @@ const EntityCountTile = ({
 };
 
 export const OwnershipCard = ({
-  entity,
   variant,
 }: {
-  entity: Entity;
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
   variant: string;
 }) => {
+  const { entity } = useEntity();
   const catalogApi = useApi(catalogApiRef);
   const {
     loading,

plugins/org/src/components/Cards/User/UserProfileCard/UserProfileCard.test.tsx

@@ -15,6 +15,7 @@
  */
 
 import { UserEntity } from '@backstage/catalog-model';
+import { EntityProvider } from '@backstage/plugin-catalog-react';
 import { renderWithEffects, wrapInTestApp } from '@backstage/test-utils';
 import React from 'react';
 import { UserProfileCard } from './UserProfileCard';
@@ -48,7 +49,11 @@ describe('UserSummary Test', () => {
 
   it('Display Profile Card', async () => {
     const rendered = await renderWithEffects(
-      wrapInTestApp(<UserProfileCard entity={userEntity} variant="gridItem" />),
+      wrapInTestApp(
+        <EntityProvider entity={userEntity}>
+          <UserProfileCard entity={userEntity} variant="gridItem" />
+        </EntityProvider>,
+      ),
     );
 
     expect(rendered.getByText('calum-leavy@example.com')).toBeInTheDocument();

plugins/org/src/components/Cards/User/UserProfileCard/UserProfileCard.tsx

@@ -19,7 +19,7 @@ import {
   UserEntity,
 } from '@backstage/catalog-model';
 import { Avatar, InfoCard } from '@backstage/core';
-import { entityRouteParams } from '@backstage/plugin-catalog-react';
+import { entityRouteParams, useEntity } from '@backstage/plugin-catalog-react';
 import {
   Box,
   Grid,
@@ -69,12 +69,13 @@ const CardTitle = ({ title }: { title?: string }) =>
   ) : null;
 
 export const UserProfileCard = ({
-  entity: user,
   variant,
 }: {
-  entity: UserEntity;
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: UserEntity;
   variant: string;
 }) => {
+  const user = useEntity().entity as UserEntity;
   const {
     metadata: { name: metaName },
     spec: { profile },

plugins/pagerduty/dev/index.tsx

@@ -14,6 +14,6 @@
  * limitations under the License.
  */
 import { createDevApp } from '@backstage/dev-utils';
-import { plugin } from '../src/plugin';
+import { pagerDutyPlugin } from '../src/plugin';
 
-createDevApp().registerPlugin(plugin).render();
+createDevApp().registerPlugin(pagerDutyPlugin).render();

plugins/pagerduty/package.json

@@ -31,6 +31,7 @@
   },
   "dependencies": {
     "@backstage/catalog-model": "^0.7.1",
+    "@backstage/plugin-catalog-react": "^0.0.2",
     "@backstage/core": "^0.6.0",
     "@backstage/theme": "^0.2.3",
     "@material-ui/core": "^4.11.0",

plugins/pagerduty/src/components/PagerDutyCard.test.tsx

@@ -17,6 +17,7 @@ import React from 'react';
 import { render, waitFor, fireEvent, act } from '@testing-library/react';
 import { PagerDutyCard } from './PagerDutyCard';
 import { Entity } from '@backstage/catalog-model';
+import { EntityProvider } from '@backstage/plugin-catalog-react';
 import { wrapInTestApp } from '@backstage/test-utils';
 import {
   alertApiRef,
@@ -80,7 +81,9 @@ describe('PageDutyCard', () => {
     const { getByText, queryByTestId } = render(
       wrapInTestApp(
         <ApiProvider apis={apis}>
-          <PagerDutyCard entity={entity} />
+          <EntityProvider entity={entity}>
+            <PagerDutyCard />
+          </EntityProvider>
         </ApiProvider>,
       ),
     );
@@ -99,7 +102,9 @@ describe('PageDutyCard', () => {
     const { getByText, queryByTestId } = render(
       wrapInTestApp(
         <ApiProvider apis={apis}>
-          <PagerDutyCard entity={entity} />
+          <EntityProvider entity={entity}>
+            <PagerDutyCard />
+          </EntityProvider>
         </ApiProvider>,
       ),
     );
@@ -114,7 +119,9 @@ describe('PageDutyCard', () => {
     const { getByText, queryByTestId } = render(
       wrapInTestApp(
         <ApiProvider apis={apis}>
-          <PagerDutyCard entity={entity} />
+          <EntityProvider entity={entity}>
+            <PagerDutyCard />
+          </EntityProvider>
         </ApiProvider>,
       ),
     );
@@ -134,7 +141,9 @@ describe('PageDutyCard', () => {
     const { getByText, queryByTestId, getByTestId, getByRole } = render(
       wrapInTestApp(
         <ApiProvider apis={apis}>
-          <PagerDutyCard entity={entity} />
+          <EntityProvider entity={entity}>
+            <PagerDutyCard />
+          </EntityProvider>
         </ApiProvider>,
       ),
     );

plugins/pagerduty/src/components/PagerDutyCard.tsx

@@ -16,6 +16,7 @@
 import React, { useState, useCallback } from 'react';
 import { useApi, Progress, HeaderIconLinkRow } from '@backstage/core';
 import { Entity } from '@backstage/catalog-model';
+import { useEntity } from '@backstage/plugin-catalog-react';
 import {
   Button,
   makeStyles,
@@ -56,11 +57,13 @@ export const isPluginApplicableToEntity = (entity: Entity) =>
   Boolean(entity.metadata.annotations?.[PAGERDUTY_INTEGRATION_KEY]);
 
 type Props = {
-  entity: Entity;
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
 };
 
-export const PagerDutyCard = ({ entity }: Props) => {
+export const PagerDutyCard = (_props: Props) => {
   const classes = useStyles();
+  const { entity } = useEntity();
   const api = useApi(pagerDutyApiRef);
   const [showDialog, setShowDialog] = useState<boolean>(false);
   const [refreshIncidents, setRefreshIncidents] = useState<boolean>(false);

plugins/pagerduty/src/index.ts

@@ -13,9 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export { plugin } from './plugin';
+export {
+  pagerDutyPlugin,
+  pagerDutyPlugin as plugin,
+  EntityPagerDutyCard,
+} from './plugin';
 export {
   isPluginApplicableToEntity,
+  isPluginApplicableToEntity as isPagerDutyAvailable,
   PagerDutyCard,
 } from './components/PagerDutyCard';
 export {

plugins/pagerduty/src/plugin.test.ts

@@ -13,10 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { plugin } from './plugin';
+import { pagerDutyPlugin } from './plugin';
 
 describe('pagerduty', () => {
   it('should export plugin', () => {
-    expect(plugin).toBeDefined();
+    expect(pagerDutyPlugin).toBeDefined();
   });
 });

plugins/pagerduty/src/plugin.ts

@@ -19,6 +19,7 @@ import {
   createRouteRef,
   discoveryApiRef,
   configApiRef,
+  createComponentExtension,
 } from '@backstage/core';
 import { pagerDutyApiRef, PagerDutyClient } from './api';
 
@@ -27,7 +28,7 @@ export const rootRouteRef = createRouteRef({
   title: 'pagerduty',
 });
 
-export const plugin = createPlugin({
+export const pagerDutyPlugin = createPlugin({
   id: 'pagerduty',
   apis: [
     createApiFactory({
@@ -38,3 +39,12 @@ export const plugin = createPlugin({
     }),
   ],
 });
+
+export const EntityPagerDutyCard = pagerDutyPlugin.provide(
+  createComponentExtension({
+    component: {
+      lazy: () =>
+        import('./components/PagerDutyCard').then(m => m.PagerDutyCard),
+    },
+  }),
+);

plugins/register-component/dev/index.tsx

@@ -15,6 +15,6 @@
  */
 
 import { createDevApp } from '@backstage/dev-utils';
-import { plugin } from '../src/plugin';
+import { registerComponentPlugin } from '../src/plugin';
 
-createDevApp().registerPlugin(plugin).render();
+createDevApp().registerPlugin(registerComponentPlugin).render();

plugins/register-component/src/index.ts

@@ -14,5 +14,9 @@
  * limitations under the License.
  */
 
-export { plugin } from './plugin';
+export {
+  registerComponentPlugin,
+  registerComponentPlugin as plugin,
+  RegisterComponentPage,
+} from './plugin';
 export { Router } from './components/Router';

plugins/register-component/src/plugin.test.ts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 
-import { plugin } from './plugin';
+import { registerComponentPlugin } from './plugin';
 
 describe('register-component', () => {
   it('should export plugin', () => {
-    expect(plugin).toBeDefined();
+    expect(registerComponentPlugin).toBeDefined();
   });
 });

plugins/register-component/src/plugin.ts

@@ -14,8 +14,29 @@
  * limitations under the License.
  */
 
-import { createPlugin } from '@backstage/core';
+import {
+  createPlugin,
+  createRoutableExtension,
+  createRouteRef,
+} from '@backstage/core';
 
-export const plugin = createPlugin({
-  id: 'register-component',
+const rootRouteRef = createRouteRef({
+  title: 'Register Component',
 });
+
+export const registerComponentPlugin = createPlugin({
+  id: 'register-component',
+  routes: {
+    root: rootRouteRef,
+  },
+});
+
+export const RegisterComponentPage = registerComponentPlugin.provide(
+  createRoutableExtension({
+    component: () =>
+      import('./components/RegisterComponentPage').then(
+        m => m.RegisterComponentPage,
+      ),
+    mountPoint: rootRouteRef,
+  }),
+);

plugins/scaffolder-backend/migrations/20210120143715_init.js

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// @ts-check
+
+/**
+ * @param {import('knex')} knex
+ */
+exports.up = async function up(knex) {
+  await knex.schema.createTable('tasks', table => {
+    table.comment('The table of scaffolder tasks');
+    table.uuid('id').primary().notNullable().comment('The ID of the task');
+    table
+      .text('spec')
+      .notNullable()
+      .comment('A JSON encoded task specification');
+    table
+      .text('status')
+      .notNullable()
+      .comment('The current status of the task');
+    table
+      .dateTime('created_at')
+      .defaultTo(knex.fn.now())
+      .notNullable()
+      .comment('The timestamp when this task was created');
+    table
+      .dateTime('last_heartbeat_at')
+      .nullable()
+      .comment('The last timestamp when a heartbeat was received');
+  });
+
+  await knex.schema.createTable('task_events', table => {
+    table.comment('The event stream a given task');
+    table
+      .bigIncrements('id')
+      .primary()
+      .notNullable()
+      .comment('The ID of the event');
+    table
+      .uuid('task_id')
+      .references('id')
+      .inTable('tasks')
+      .notNullable()
+      .onDelete('CASCADE')
+      .comment('The task that generated the event');
+    table
+      .text('body')
+      .notNullable()
+      .comment('The JSON encoded body of the event');
+    table.text('event_type').notNullable().comment('The type of event');
+    table
+      .timestamp('created_at')
+      .defaultTo(knex.fn.now())
+      .notNullable()
+      .comment('The timestamp when this event was generated');
+
+    table.index(['task_id'], 'task_events_task_id_idx');
+  });
+};
+
+/**
+ * @param {import('knex')} knex
+ */
+exports.down = async function down(knex) {
+  if (knex.client.config.client !== 'sqlite3') {
+    await knex.schema.alterTable('task_events', table => {
+      table.dropIndex([], 'ctask_events_task_id_idx');
+    });
+  }
+  await knex.schema.dropTable('task_events');
+  await knex.schema.dropTable('tasks');
+};

plugins/scaffolder-backend/package.json

@@ -53,6 +53,7 @@
     "helmet": "^4.0.0",
     "isomorphic-git": "^1.8.0",
     "jsonschema": "^1.2.6",
+    "knex": "^0.21.6",
     "morgan": "^1.10.0",
     "uuid": "^8.2.0",
     "winston": "^3.2.1",
@@ -71,6 +72,7 @@
   },
   "files": [
     "dist",
+    "migrations",
     "config.d.ts"
   ],
   "configSchema": "config.d.ts"

plugins/scaffolder-backend/src/scaffolder/stages/legacy.ts

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { TemplateActionRegistry } from '../tasks/TemplateConverter';
+import { FilePreparer, PreparerBuilder } from './prepare';
+import Docker from 'dockerode';
+import { TemplaterBuilder, TemplaterValues } from './templater';
+import { PublisherBuilder } from './publish';
+
+type Options = {
+  dockerClient: Docker;
+  preparers: PreparerBuilder;
+  templaters: TemplaterBuilder;
+  publishers: PublisherBuilder;
+};
+
+export function registerLegacyActions(
+  registry: TemplateActionRegistry,
+  options: Options,
+) {
+  const { dockerClient, preparers, templaters, publishers } = options;
+
+  registry.register({
+    id: 'legacy:prepare',
+    async handler(ctx) {
+      const { protocol, url } = ctx.parameters;
+      const preparer =
+        protocol === 'file' ? new FilePreparer() : preparers.get(url as string);
+
+      ctx.logger.info('Prepare the skeleton');
+      await preparer.prepare({
+        url: url as string,
+        logger: ctx.logger,
+        workspacePath: ctx.workspacePath,
+      });
+    },
+  });
+
+  registry.register({
+    id: 'legacy:template',
+    async handler(ctx) {
+      const { logger } = ctx;
+
+      const templater = templaters.get(ctx.parameters.templater as string);
+
+      logger.info('Run the templater');
+      await templater.run({
+        workspacePath: ctx.workspacePath,
+        dockerClient,
+        logStream: ctx.logStream,
+        values: ctx.parameters.values as TemplaterValues,
+      });
+    },
+  });
+
+  registry.register({
+    id: 'legacy:publish',
+    async handler(ctx) {
+      const { values } = ctx.parameters;
+      if (
+        typeof values !== 'object' ||
+        values === null ||
+        Array.isArray(values)
+      ) {
+        throw new Error(
+          `Invalid values passed to publish, got ${typeof values}`,
+        );
+      }
+      const storePath = values.storePath as unknown;
+      if (typeof storePath !== 'string') {
+        throw new Error(
+          `Invalid store path passed to publish, got ${typeof storePath}`,
+        );
+      }
+      const owner = values.owner as unknown;
+      if (typeof owner !== 'string') {
+        throw new Error(`Invalid owner passed to publish, got ${typeof owner}`);
+      }
+
+      const publisher = publishers.get(storePath);
+      ctx.logger.info('Will now store the template');
+      const { remoteUrl, catalogInfoUrl } = await publisher.publish({
+        values: {
+          ...values,
+          owner,
+          storePath,
+        },
+        workspacePath: ctx.workspacePath,
+        logger: ctx.logger,
+      });
+      ctx.output('remoteUrl', remoteUrl);
+      if (catalogInfoUrl) {
+        ctx.output('catalogInfoUrl', catalogInfoUrl);
+      }
+    },
+  });
+}

plugins/scaffolder-backend/src/scaffolder/tasks/DatabaseTaskStore.ts

@@ -0,0 +1,272 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { JsonObject } from '@backstage/config';
+import {
+  ConflictError,
+  NotFoundError,
+  resolvePackagePath,
+} from '@backstage/backend-common';
+import Knex from 'knex';
+import { v4 as uuid } from 'uuid';
+import {
+  DbTaskEventRow,
+  DbTaskRow,
+  Status,
+  TaskEventType,
+  TaskSpec,
+  TaskStore,
+  TaskStoreEmitOptions,
+  TaskStoreGetEventsOptions,
+} from './types';
+
+const migrationsDir = resolvePackagePath(
+  '@backstage/plugin-scaffolder-backend',
+  'migrations',
+);
+
+export type RawDbTaskRow = {
+  id: string;
+  spec: string;
+  status: Status;
+  last_heartbeat_at?: string;
+  created_at: string;
+};
+
+export type RawDbTaskEventRow = {
+  id: number;
+  task_id: string;
+  body: string;
+  event_type: TaskEventType;
+  created_at: string;
+};
+
+export class DatabaseTaskStore implements TaskStore {
+  static async create(knex: Knex): Promise<DatabaseTaskStore> {
+    await knex.migrate.latest({
+      directory: migrationsDir,
+    });
+    return new DatabaseTaskStore(knex);
+  }
+
+  constructor(private readonly db: Knex) {}
+
+  async get(taskId: string): Promise<DbTaskRow> {
+    const [result] = await this.db<RawDbTaskRow>('tasks')
+      .where({ id: taskId })
+      .select();
+    if (!result) {
+      throw new NotFoundError(`No task with id '${taskId}' found`);
+    }
+    try {
+      const spec = JSON.parse(result.spec);
+      return {
+        id: result.id,
+        spec,
+        status: result.status,
+        lastHeartbeatAt: result.last_heartbeat_at,
+        createdAt: result.created_at,
+      };
+    } catch (error) {
+      throw new Error(`Failed to parse spec of task '${taskId}', ${error}`);
+    }
+  }
+
+  async createTask(spec: TaskSpec): Promise<{ taskId: string }> {
+    const taskId = uuid();
+    await this.db<RawDbTaskRow>('tasks').insert({
+      id: taskId,
+      spec: JSON.stringify(spec),
+      status: 'open',
+    });
+    return { taskId };
+  }
+
+  async claimTask(): Promise<DbTaskRow | undefined> {
+    return this.db.transaction(async tx => {
+      const [task] = await tx<RawDbTaskRow>('tasks')
+        .where({
+          status: 'open',
+        })
+        .limit(1)
+        .select();
+
+      if (!task) {
+        return undefined;
+      }
+
+      const updateCount = await tx<RawDbTaskRow>('tasks')
+        .where({ id: task.id, status: 'open' })
+        .update({
+          status: 'processing',
+          last_heartbeat_at: this.db.fn.now(),
+        });
+
+      if (updateCount < 1) {
+        return undefined;
+      }
+
+      try {
+        const spec = JSON.parse(task.spec);
+        return {
+          id: task.id,
+          spec,
+          status: 'processing',
+          lastHeartbeatAt: task.last_heartbeat_at,
+          createdAt: task.created_at,
+        };
+      } catch (error) {
+        throw new Error(`Failed to parse spec of task '${task.id}', ${error}`);
+      }
+    });
+  }
+
+  async heartbeatTask(taskId: string): Promise<void> {
+    const updateCount = await this.db<RawDbTaskRow>('tasks')
+      .where({ id: taskId, status: 'processing' })
+      .update({
+        last_heartbeat_at: this.db.fn.now(),
+      });
+    if (updateCount === 0) {
+      throw new ConflictError(`No running task with taskId ${taskId} found`);
+    }
+  }
+
+  async listStaleTasks({
+    timeoutS,
+  }: {
+    timeoutS: number;
+  }): Promise<{
+    tasks: { taskId: string }[];
+  }> {
+    const rawRows = await this.db<RawDbTaskRow>('tasks')
+      .where('status', 'processing')
+      .andWhere(
+        'last_heartbeat_at',
+        '<=',
+        this.db.client.config.client === 'sqlite3'
+          ? this.db.raw(`datetime('now', ?)`, [`-${timeoutS} seconds`])
+          : this.db.raw(`dateadd('second', ?, ?)`, [
+              `-${timeoutS}`,
+              this.db.fn.now(),
+            ]),
+      );
+    const tasks = rawRows.map(row => ({
+      taskId: row.id,
+    }));
+    return { tasks };
+  }
+
+  async completeTask({
+    taskId,
+    status,
+    eventBody,
+  }: {
+    taskId: string;
+    status: Status;
+    eventBody: JsonObject;
+  }): Promise<void> {
+    let oldStatus: string;
+    if (status === 'failed' || status === 'completed') {
+      oldStatus = 'processing';
+    } else {
+      throw new Error(
+        `Invalid status update of run '${taskId}' to status '${status}'`,
+      );
+    }
+    await this.db.transaction(async tx => {
+      const [task] = await tx<RawDbTaskRow>('tasks')
+        .where({
+          id: taskId,
+        })
+        .limit(1)
+        .select();
+
+      if (!task) {
+        throw new Error(`No task with taskId ${taskId} found`);
+      }
+      if (task.status !== oldStatus) {
+        throw new ConflictError(
+          `Refusing to update status of run '${taskId}' to status '${status}' ` +
+            `as it is currently '${task.status}', expected '${oldStatus}'`,
+        );
+      }
+      const updateCount = await tx<RawDbTaskRow>('tasks')
+        .where({
+          id: taskId,
+          status: oldStatus,
+        })
+        .update({
+          status,
+        });
+      if (updateCount !== 1) {
+        throw new ConflictError(
+          `Failed to update status to '${status}' for taskId ${taskId}`,
+        );
+      }
+
+      await tx<RawDbTaskEventRow>('task_events').insert({
+        task_id: taskId,
+        event_type: 'completion',
+        body: JSON.stringify(eventBody),
+      });
+    });
+  }
+
+  async emitLogEvent({ taskId, body }: TaskStoreEmitOptions): Promise<void> {
+    const serliazedBody = JSON.stringify(body);
+    await this.db<RawDbTaskEventRow>('task_events').insert({
+      task_id: taskId,
+      event_type: 'log',
+      body: serliazedBody,
+    });
+  }
+
+  async listEvents({
+    taskId,
+    after,
+  }: TaskStoreGetEventsOptions): Promise<{ events: DbTaskEventRow[] }> {
+    const rawEvents = await this.db<RawDbTaskEventRow>('task_events')
+      .where({
+        task_id: taskId,
+      })
+      .andWhere(builder => {
+        if (typeof after === 'number') {
+          builder.where('id', '>', after).orWhere('event_type', 'completion');
+        }
+      })
+      .orderBy('id')
+      .select();
+
+    const events = rawEvents.map(event => {
+      try {
+        const body = JSON.parse(event.body) as JsonObject;
+        return {
+          id: event.id,
+          taskId,
+          body,
+          type: event.event_type,
+          createdAt: event.created_at,
+        };
+      } catch (error) {
+        throw new Error(
+          `Failed to parse event body from event taskId=${taskId} id=${event.id}, ${error}`,
+        );
+      }
+    });
+    return { events };
+  }
+}

plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.test.ts

@@ -0,0 +1,183 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  getVoidLogger,
+  SingleConnectionDatabaseManager,
+} from '@backstage/backend-common';
+import { ConfigReader } from '@backstage/config';
+import { DatabaseTaskStore } from './DatabaseTaskStore';
+import { StorageTaskBroker, TaskAgent } from './StorageTaskBroker';
+import { TaskSpec, DbTaskEventRow } from './types';
+
+async function createStore(): Promise<DatabaseTaskStore> {
+  const manager = SingleConnectionDatabaseManager.fromConfig(
+    new ConfigReader({
+      backend: {
+        database: {
+          client: 'sqlite3',
+          connection: ':memory:',
+        },
+      },
+    }),
+  ).forPlugin('scaffolder');
+  return await DatabaseTaskStore.create(await manager.getClient());
+}
+
+describe('StorageTaskBroker', () => {
+  let storage: DatabaseTaskStore;
+
+  beforeAll(async () => {
+    storage = await createStore();
+  });
+
+  const logger = getVoidLogger();
+  it('should claim a dispatched work item', async () => {
+    const broker = new StorageTaskBroker(storage, logger);
+    await broker.dispatch({ steps: [] });
+    await expect(broker.claim()).resolves.toEqual(expect.any(TaskAgent));
+  });
+
+  it('should wait for a dispatched work item', async () => {
+    const broker = new StorageTaskBroker(storage, logger);
+    const promise = broker.claim();
+
+    await expect(Promise.race([promise, 'waiting'])).resolves.toBe('waiting');
+
+    await broker.dispatch({ steps: [] });
+    await expect(promise).resolves.toEqual(expect.any(TaskAgent));
+  });
+
+  it('should dispatch multiple items and claim them in order', async () => {
+    const broker = new StorageTaskBroker(storage, logger);
+    await broker.dispatch({ steps: [{ id: 'a' }] } as TaskSpec);
+    await broker.dispatch({ steps: [{ id: 'b' }] } as TaskSpec);
+    await broker.dispatch({ steps: [{ id: 'c' }] } as TaskSpec);
+
+    const taskA = await broker.claim();
+    const taskB = await broker.claim();
+    const taskC = await broker.claim();
+    await expect(taskA).toEqual(expect.any(TaskAgent));
+    await expect(taskB).toEqual(expect.any(TaskAgent));
+    await expect(taskC).toEqual(expect.any(TaskAgent));
+    await expect(taskA.spec.steps[0].id).toBe('a');
+    await expect(taskB.spec.steps[0].id).toBe('b');
+    await expect(taskC.spec.steps[0].id).toBe('c');
+  });
+
+  it('should complete a task', async () => {
+    const broker = new StorageTaskBroker(storage, logger);
+    const dispatchResult = await broker.dispatch({ steps: [] });
+    const task = await broker.claim();
+    await task.complete('completed');
+    const taskRow = await storage.get(dispatchResult.taskId);
+    expect(taskRow.status).toBe('completed');
+  }, 10000);
+
+  it('should fail a task', async () => {
+    const broker = new StorageTaskBroker(storage, logger);
+    const dispatchResult = await broker.dispatch({ steps: [] });
+    const task = await broker.claim();
+    await task.complete('failed');
+    const taskRow = await storage.get(dispatchResult.taskId);
+    expect(taskRow.status).toBe('failed');
+  });
+
+  it('multiple brokers should be able to observe a single task', async () => {
+    const broker1 = new StorageTaskBroker(storage, logger);
+    const broker2 = new StorageTaskBroker(storage, logger);
+
+    const { taskId } = await broker1.dispatch({ steps: [] });
+
+    const logPromise = new Promise<DbTaskEventRow[]>(resolve => {
+      const observedEvents = new Array<DbTaskEventRow>();
+
+      broker2.observe({ taskId, after: undefined }, (_err, { events }) => {
+        observedEvents.push(...events);
+        if (events.some(e => e.type === 'completion')) {
+          resolve(observedEvents);
+        }
+      });
+    });
+    const task = await broker1.claim();
+    await task.emitLog('log 1');
+    await task.emitLog('log 2');
+    await task.emitLog('log 3');
+    await task.complete('completed');
+
+    const logs = await logPromise;
+    expect(logs.map(l => l.body.message, logger)).toEqual([
+      'log 1',
+      'log 2',
+      'log 3',
+      'Run completed with status: completed',
+    ]);
+
+    const afterLogs = await new Promise<string[]>(resolve => {
+      broker2.observe({ taskId, after: logs[1].id }, (_err, { events }) =>
+        resolve(events.map(e => e.body.message as string)),
+      );
+    });
+    expect(afterLogs).toEqual([
+      'log 3',
+      'Run completed with status: completed',
+    ]);
+  });
+
+  it('should heartbeat', async () => {
+    const broker = new StorageTaskBroker(storage, logger);
+    const { taskId } = await broker.dispatch({ steps: [] });
+    const task = await broker.claim();
+
+    const initialTask = await storage.get(taskId);
+
+    for (;;) {
+      const maybeTask = await storage.get(taskId);
+      if (maybeTask.lastHeartbeatAt !== initialTask.lastHeartbeatAt) {
+        break;
+      }
+      await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    await task.complete('completed');
+    expect.assertions(0);
+  });
+
+  it('should be update the status to failed if heartbeat fails', async () => {
+    const broker = new StorageTaskBroker(storage, logger);
+    const { taskId } = await broker.dispatch({ steps: [] });
+    const task = await broker.claim();
+
+    jest
+      .spyOn((task as any).storage, 'heartbeatTask')
+      .mockRejectedValue(new Error('nah m8'));
+
+    const intervalId = setInterval(() => {
+      broker.vacuumTasks({ timeoutS: 2 }).catch(fail);
+    }, 500);
+
+    for (;;) {
+      const maybeTask = await storage.get(taskId);
+      if (maybeTask.status === 'failed') {
+        break;
+      }
+      await new Promise(resolve => setTimeout(resolve, 50));
+    }
+
+    clearInterval(intervalId);
+
+    expect(task.done).toBe(true);
+  });
+});

plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts

@@ -0,0 +1,205 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Logger } from 'winston';
+import {
+  CompletedTaskState,
+  Task,
+  TaskSpec,
+  TaskStore,
+  TaskBroker,
+  DispatchResult,
+  DbTaskEventRow,
+} from './types';
+
+export class TaskAgent implements Task {
+  private isDone = false;
+
+  private heartbeatTimeoutId?: ReturnType<typeof setInterval>;
+
+  static create(state: TaskState, storage: TaskStore, logger: Logger) {
+    const agent = new TaskAgent(state, storage, logger);
+    agent.startTimeout();
+    return agent;
+  }
+
+  // Runs heartbeat internally
+  private constructor(
+    private readonly state: TaskState,
+    private readonly storage: TaskStore,
+    private readonly logger: Logger,
+  ) {}
+
+  get spec() {
+    return this.state.spec;
+  }
+
+  async getWorkspaceName() {
+    return this.state.taskId;
+  }
+
+  get done() {
+    return this.isDone;
+  }
+
+  async emitLog(message: string): Promise<void> {
+    await this.storage.emitLogEvent({
+      taskId: this.state.taskId,
+      body: { message },
+    });
+  }
+
+  async complete(result: CompletedTaskState): Promise<void> {
+    await this.storage.completeTask({
+      taskId: this.state.taskId,
+      status: result === 'failed' ? 'failed' : 'completed',
+      eventBody: { message: `Run completed with status: ${result}` },
+    });
+    this.isDone = true;
+    if (this.heartbeatTimeoutId) {
+      clearTimeout(this.heartbeatTimeoutId);
+    }
+  }
+
+  private startTimeout() {
+    this.heartbeatTimeoutId = setTimeout(async () => {
+      try {
+        await this.storage.heartbeatTask(this.state.taskId);
+        this.startTimeout();
+      } catch (error) {
+        this.isDone = true;
+
+        this.logger.error(
+          `Heartbeat for task ${this.state.taskId} failed`,
+          error,
+        );
+      }
+    }, 1000);
+  }
+}
+
+interface TaskState {
+  spec: TaskSpec;
+  taskId: string;
+}
+
+function defer() {
+  let resolve = () => {};
+  const promise = new Promise<void>(_resolve => {
+    resolve = _resolve;
+  });
+  return { promise, resolve };
+}
+
+export class StorageTaskBroker implements TaskBroker {
+  constructor(
+    private readonly storage: TaskStore,
+    private readonly logger: Logger,
+  ) {}
+  private deferredDispatch = defer();
+
+  async claim(): Promise<Task> {
+    for (;;) {
+      const pendingTask = await this.storage.claimTask();
+      if (pendingTask) {
+        return TaskAgent.create(
+          {
+            taskId: pendingTask.id,
+            spec: pendingTask.spec,
+          },
+          this.storage,
+          this.logger,
+        );
+      }
+
+      await this.waitForDispatch();
+    }
+  }
+
+  async dispatch(spec: TaskSpec): Promise<DispatchResult> {
+    const taskRow = await this.storage.createTask(spec);
+    this.signalDispatch();
+    return {
+      taskId: taskRow.taskId,
+    };
+  }
+
+  observe(
+    options: {
+      taskId: string;
+      after: number | undefined;
+    },
+    callback: (
+      error: Error | undefined,
+      result: { events: DbTaskEventRow[] },
+    ) => void,
+  ): () => void {
+    const { taskId } = options;
+
+    let cancelled = false;
+    const unsubscribe = () => {
+      cancelled = true;
+    };
+
+    (async () => {
+      let after = options.after;
+      while (!cancelled) {
+        const result = await this.storage.listEvents({ taskId, after: after });
+        const { events } = result;
+        if (events.length) {
+          after = events[events.length - 1].id;
+          try {
+            callback(undefined, result);
+          } catch (error) {
+            callback(error, { events: [] });
+          }
+        }
+
+        await new Promise(resolve => setTimeout(resolve, 1000));
+      }
+    })();
+
+    return unsubscribe;
+  }
+
+  async vacuumTasks(timeoutS: { timeoutS: number }): Promise<void> {
+    const { tasks } = await this.storage.listStaleTasks(timeoutS);
+    await Promise.all(
+      tasks.map(async task => {
+        try {
+          await this.storage.completeTask({
+            taskId: task.taskId,
+            status: 'failed',
+            eventBody: {
+              message:
+                'The task was cancelled because the task worker lost connection to the task broker',
+            },
+          });
+        } catch (error) {
+          this.logger.warn(`Failed to cancel task '${task.taskId}', ${error}`);
+        }
+      }),
+    );
+  }
+
+  private waitForDispatch() {
+    return this.deferredDispatch.promise;
+  }
+
+  private signalDispatch() {
+    this.deferredDispatch.resolve();
+    this.deferredDispatch = defer();
+  }
+}

plugins/scaffolder-backend/src/scaffolder/tasks/TaskWorker.ts

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { PassThrough } from 'stream';
+import { Logger } from 'winston';
+import * as winston from 'winston';
+import { JsonValue } from '@backstage/config';
+import { TaskBroker, Task } from './types';
+import fs from 'fs-extra';
+import path from 'path';
+import { TemplateActionRegistry } from './TemplateConverter';
+
+type Options = {
+  logger: Logger;
+  taskBroker: TaskBroker;
+  workingDirectory: string;
+  actionRegistry: TemplateActionRegistry;
+};
+
+export class TaskWorker {
+  constructor(private readonly options: Options) {}
+
+  start() {
+    (async () => {
+      for (;;) {
+        const task = await this.options.taskBroker.claim();
+        await this.runOneTask(task);
+      }
+    })();
+  }
+
+  async runOneTask(task: Task) {
+    try {
+      const { actionRegistry, logger } = this.options;
+
+      const workspacePath = path.join(
+        this.options.workingDirectory,
+        await task.getWorkspaceName(),
+      );
+      await fs.ensureDir(workspacePath);
+
+      const taskLogger = winston.createLogger({
+        level: process.env.LOG_LEVEL || 'info',
+        format: winston.format.combine(
+          winston.format.colorize(),
+          winston.format.timestamp(),
+          winston.format.simple(),
+        ),
+        defaultMeta: {},
+      });
+
+      const stream = new PassThrough();
+      stream.on('data', data => {
+        const message = data.toString().trim();
+        if (message?.length > 1) task.emitLog(message);
+      });
+
+      taskLogger.add(new winston.transports.Stream({ stream }));
+
+      // Give us some time to curl observe
+      task.emitLog('Task claimed, waiting ...');
+      await new Promise(resolve => setTimeout(resolve, 5000));
+      task.emitLog(`Starting up work with ${task.spec.steps.length} steps`);
+
+      const outputs: { [name: string]: JsonValue } = {};
+
+      for (const step of task.spec.steps) {
+        task.emitLog(`Beginning step ${step.name}`);
+
+        const action = actionRegistry.get(step.action);
+        if (!action) {
+          throw new Error(`Action '${step.action}' does not exist`);
+        }
+
+        // TODO: substitute any placeholders with output from previous steps
+        const parameters = step.parameters!;
+
+        await action.handler({
+          logger,
+          logStream: stream,
+          parameters,
+          workspacePath,
+          output(name: string, value: JsonValue) {
+            outputs[name] = value;
+          },
+        });
+
+        task.emitLog(`Finished step ${step.name}`);
+      }
+
+      await task.complete('completed');
+    } catch (error) {
+      task.emitLog(String(error.stack));
+      await task.complete('failed');
+    }
+  }
+}

plugins/scaffolder-backend/src/scaffolder/tasks/TemplateConverter.ts

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { resolve as resolvePath } from 'path';
+import { JsonValue } from '@backstage/config';
+import { TemplateEntityV1alpha1 } from '@backstage/catalog-model';
+import { Logger } from 'winston';
+import type { Writable } from 'stream';
+
+import { TaskSpec } from './types';
+import { ConflictError, NotFoundError } from '@backstage/backend-common';
+import {
+  getTemplaterKey,
+  joinGitUrlPath,
+  parseLocationAnnotation,
+  TemplaterValues,
+} from '../stages';
+
+export function templateEntityToSpec(
+  template: TemplateEntityV1alpha1,
+  values: TemplaterValues,
+): TaskSpec {
+  const steps: TaskSpec['steps'] = [];
+
+  const { protocol, location } = parseLocationAnnotation(template);
+
+  let url: string;
+  if (protocol === 'file') {
+    const path = resolvePath(location, template.spec.path || '.');
+
+    url = `file://${path}`;
+  } else {
+    url = joinGitUrlPath(location, template.spec.path);
+  }
+  const templater = getTemplaterKey(template);
+
+  steps.push({
+    id: 'prepare',
+    name: 'Prepare',
+    action: 'legacy:prepare',
+    parameters: {
+      protocol,
+      url,
+    },
+  });
+
+  steps.push({
+    id: 'template',
+    name: 'Template',
+    action: 'legacy:template',
+    parameters: {
+      templater,
+      values,
+    },
+  });
+
+  steps.push({
+    id: 'publish',
+    name: 'Publishing',
+    action: 'legacy:publish',
+    parameters: {
+      values,
+    },
+  });
+
+  return { steps };
+}
+
+type ActionContext = {
+  logger: Logger;
+  logStream: Writable;
+
+  workspacePath: string;
+  parameters: { [name: string]: JsonValue };
+  output(name: string, value: JsonValue): void;
+};
+
+type TemplateAction = {
+  id: string;
+  handler: (ctx: ActionContext) => Promise<void>;
+};
+
+export class TemplateActionRegistry {
+  private readonly actions = new Map<string, TemplateAction>();
+
+  register(action: TemplateAction) {
+    if (this.actions.has(action.id)) {
+      throw new ConflictError(
+        `Template action with ID '${action.id}' has already been registered`,
+      );
+    }
+    this.actions.set(action.id, action);
+  }
+
+  get(actionId: string): TemplateAction {
+    const action = this.actions.get(actionId);
+    if (!action) {
+      throw new NotFoundError(
+        `Template action with ID '${actionId}' is not registered.`,
+      );
+    }
+    return action;
+  }
+}

plugins/scaffolder-backend/src/scaffolder/tasks/index.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { DatabaseTaskStore } from './DatabaseTaskStore';
+export { StorageTaskBroker } from './StorageTaskBroker';
+export { TaskWorker } from './TaskWorker';

plugins/scaffolder-backend/src/scaffolder/tasks/types.ts

@@ -0,0 +1,111 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { JsonValue, JsonObject } from '@backstage/config';
+
+export type Status =
+  | 'open'
+  | 'processing'
+  | 'failed'
+  | 'cancelled'
+  | 'completed';
+
+export type CompletedTaskState = 'failed' | 'completed';
+
+export type DbTaskRow = {
+  id: string;
+  spec: TaskSpec;
+  status: Status;
+  createdAt: string;
+  lastHeartbeatAt?: string;
+};
+
+export type TaskEventType = 'completion' | 'log';
+export type DbTaskEventRow = {
+  id: number;
+  taskId: string;
+  body: JsonObject;
+  type: TaskEventType;
+  createdAt: string;
+};
+
+export type TaskSpec = {
+  steps: Array<{
+    id: string;
+    name: string;
+    action: string;
+    parameters?: { [name: string]: JsonValue };
+  }>;
+};
+
+export type DispatchResult = {
+  taskId: string;
+};
+
+export interface Task {
+  spec: TaskSpec;
+  done: boolean;
+  emitLog(message: string): Promise<void>;
+  complete(result: CompletedTaskState): Promise<void>;
+  getWorkspaceName(): Promise<string>;
+}
+
+export interface TaskBroker {
+  claim(): Promise<Task>;
+  dispatch(spec: TaskSpec): Promise<DispatchResult>;
+  vacuumTasks(timeoutS: { timeoutS: number }): Promise<void>;
+  observe(
+    options: {
+      taskId: string;
+      after: number | undefined;
+    },
+    callback: (
+      error: Error | undefined,
+      result: { events: DbTaskEventRow[] },
+    ) => void,
+  ): () => void;
+}
+
+export type TaskStoreEmitOptions = {
+  taskId: string;
+  body: JsonObject;
+};
+
+export type TaskStoreGetEventsOptions = {
+  taskId: string;
+  after?: number | undefined;
+};
+export interface TaskStore {
+  createTask(task: TaskSpec): Promise<{ taskId: string }>;
+  claimTask(): Promise<DbTaskRow | undefined>;
+  completeTask(options: {
+    taskId: string;
+    status: Status;
+    eventBody: JsonObject;
+  }): Promise<void>;
+  heartbeatTask(taskId: string): Promise<void>;
+  listStaleTasks(options: {
+    timeoutS: number;
+  }): Promise<{
+    tasks: { taskId: string }[];
+  }>;
+
+  emitLogEvent({ taskId, body }: TaskStoreEmitOptions): Promise<void>;
+  listEvents({
+    taskId,
+    after,
+  }: TaskStoreGetEventsOptions): Promise<{ events: DbTaskEventRow[] }>;
+}

plugins/scaffolder-backend/src/service/helpers.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import os from 'os';
+import fs from 'fs-extra';
+import { Logger } from 'winston';
+import { Config } from '@backstage/config';
+
+export async function getWorkingDirectory(
+  config: Config,
+  logger: Logger,
+): Promise<string> {
+  if (!config.has('backend.workingDirectory')) {
+    return os.tmpdir();
+  }
+
+  const workingDirectory = config.getString('backend.workingDirectory');
+  try {
+    // Check if working directory exists and is writable
+    await fs.access(workingDirectory, fs.constants.F_OK | fs.constants.W_OK);
+    logger.info(`using working directory: ${workingDirectory}`);
+  } catch (err) {
+    logger.error(
+      `working directory ${workingDirectory} ${
+        err.code === 'ENOENT' ? 'does not exist' : 'is not writable'
+      }`,
+    );
+    throw err;
+  }
+  return workingDirectory;
+}

plugins/scaffolder-backend/src/service/router.test.ts

@@ -16,6 +16,7 @@
 
 const mockAccess = jest.fn();
 jest.doMock('fs-extra', () => ({
+  access: mockAccess,
   promises: {
     access: mockAccess,
   },
@@ -27,7 +28,11 @@ jest.doMock('fs-extra', () => ({
   remove: jest.fn(),
 }));
 
-import { getVoidLogger } from '@backstage/backend-common';
+import {
+  SingleConnectionDatabaseManager,
+  PluginDatabaseManager,
+  getVoidLogger,
+} from '@backstage/backend-common';
 import { ConfigReader } from '@backstage/config';
 import express from 'express';
 import request from 'supertest';
@@ -41,6 +46,19 @@ const generateEntityClient: any = (template: any) => ({
   findTemplate: () => Promise.resolve(template),
 });
 
+function createDatabase(): PluginDatabaseManager {
+  return SingleConnectionDatabaseManager.fromConfig(
+    new ConfigReader({
+      backend: {
+        database: {
+          client: 'sqlite3',
+          connection: ':memory:',
+        },
+      },
+    }),
+  ).forPlugin('scaffolder');
+}
+
 describe('createRouter - working directory', () => {
   const mockPrepare = jest.fn();
   const mockPreparers = new Preparers();
@@ -78,7 +96,6 @@ describe('createRouter - working directory', () => {
   };
 
   const mockedEntityClient = generateEntityClient(template);
-
   it('should throw an error when working directory does not exist or is not writable', async () => {
     mockAccess.mockImplementation(() => {
       throw new Error('access error');
@@ -93,6 +110,7 @@ describe('createRouter - working directory', () => {
         config: new ConfigReader(workDirConfig('/path')),
         dockerClient: new Docker(),
         entityClient: mockedEntityClient,
+        database: createDatabase(),
       }),
     ).rejects.toThrow('access error');
   });
@@ -106,6 +124,7 @@ describe('createRouter - working directory', () => {
       config: new ConfigReader(workDirConfig('/path')),
       dockerClient: new Docker(),
       entityClient: mockedEntityClient,
+      database: createDatabase(),
     });
 
     const app = express().use(router);
@@ -134,6 +153,7 @@ describe('createRouter - working directory', () => {
       config: new ConfigReader({}),
       dockerClient: new Docker(),
       entityClient: mockedEntityClient,
+      database: createDatabase(),
     });
 
     const app = express().use(router);
@@ -203,6 +223,7 @@ describe('createRouter', () => {
       config: new ConfigReader({}),
       dockerClient: new Docker(),
       entityClient: generateEntityClient(template),
+      database: createDatabase(),
     });
     app = express().use(router);
   });

plugins/scaffolder-backend/src/service/router.ts

@@ -33,6 +33,18 @@ import {
 import { CatalogEntityClient } from '../lib/catalog';
 import { validate, ValidatorResult } from 'jsonschema';
 import parseGitUrl from 'git-url-parse';
+import {
+  DatabaseTaskStore,
+  StorageTaskBroker,
+  TaskWorker,
+} from '../scaffolder/tasks';
+import {
+  TemplateActionRegistry,
+  templateEntityToSpec,
+} from '../scaffolder/tasks/TemplateConverter';
+import { registerLegacyActions } from '../scaffolder/stages/legacy';
+import { getWorkingDirectory } from './helpers';
+import { PluginDatabaseManager } from '@backstage/backend-common';
 
 export interface RouterOptions {
   preparers: PreparerBuilder;
@@ -43,6 +55,7 @@ export interface RouterOptions {
   config: Config;
   dockerClient: Docker;
   entityClient: CatalogEntityClient;
+  database: PluginDatabaseManager;
 }
 
 export async function createRouter(
@@ -59,11 +72,34 @@ export async function createRouter(
     config,
     dockerClient,
     entityClient,
+    database,
   } = options;
 
   const logger = parentLogger.child({ plugin: 'scaffolder' });
+  const workingDirectory = await getWorkingDirectory(config, logger);
   const jobProcessor = await JobProcessor.fromConfig({ config, logger });
 
+  const databaseTaskStore = await DatabaseTaskStore.create(
+    await database.getClient(),
+  );
+  const taskBroker = new StorageTaskBroker(databaseTaskStore, logger);
+  const actionRegistry = new TemplateActionRegistry();
+  const worker = new TaskWorker({
+    logger,
+    taskBroker,
+    actionRegistry,
+    workingDirectory,
+  });
+
+  registerLegacyActions(actionRegistry, {
+    dockerClient,
+    preparers,
+    publishers,
+    templaters,
+  });
+
+  worker.start();
+
   router
     .get('/v1/job/:jobId', ({ params }, res) => {
       const job = jobProcessor.get(params.jobId);
@@ -184,6 +220,75 @@ export async function createRouter(
       res.status(201).json({ id: job.id });
     });
 
+  // NOTE: The v2 API is unstable
+  router
+    .post('/v2/tasks', async (req, res) => {
+      const templateName: string = req.body.templateName;
+      const values: TemplaterValues = {
+        ...req.body.values,
+        destination: {
+          git: parseGitUrl(req.body.values.storePath),
+        },
+      };
+      const template = await entityClient.findTemplate(templateName);
+
+      const validationResult: ValidatorResult = validate(
+        values,
+        template.spec.schema,
+      );
+
+      if (!validationResult.valid) {
+        res.status(400).json({ errors: validationResult.errors });
+        return;
+      }
+      const taskSpec = templateEntityToSpec(template, values);
+      const result = await taskBroker.dispatch(taskSpec);
+
+      res.status(201).json({ id: result.taskId });
+    })
+    .get('/v2/tasks/:taskId/eventstream', async (req, res) => {
+      const { taskId } = req.params;
+      const after = Number(req.query.after) || undefined;
+      logger.debug(`Event stream observing taskId '${taskId}' opened`);
+
+      // Mandatory headers and http status to keep connection open
+      res.writeHead(200, {
+        Connection: 'keep-alive',
+        'Cache-Control': 'no-cache',
+        'Content-Type': 'text/event-stream',
+      });
+
+      // After client opens connection send all events as string
+      const unsubscribe = taskBroker.observe(
+        { taskId, after },
+        (error, { events }) => {
+          if (error) {
+            logger.error(
+              `Received error from event stream when observing taskId '${taskId}', ${error}`,
+            );
+          }
+
+          for (const event of events) {
+            res.write(
+              `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`,
+            );
+            if (event.type === 'completion') {
+              unsubscribe();
+              // Closing the event stream here would cause the frontend
+              // to automatically reconnect because it lost connection.
+            }
+          }
+          res.flush();
+        },
+      );
+      // When client closes connection we update the clients list
+      // avoiding the disconnected one
+      req.on('close', () => {
+        unsubscribe();
+        logger.debug(`Event stream observing taskId '${taskId}' closed`);
+      });
+    });
+
   const app = express();
   app.set('logger', logger);
   app.use('/', router);

plugins/search/dev/index.tsx

@@ -14,6 +14,6 @@
  * limitations under the License.
  */
 import { createDevApp } from '@backstage/dev-utils';
-import { plugin } from '../src/plugin';
+import { searchPlugin } from '../src/plugin';
 
-createDevApp().registerPlugin(plugin).render();
+createDevApp().registerPlugin(searchPlugin).render();

plugins/search/src/index.ts

@@ -13,5 +13,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export { plugin } from './plugin';
-export * from './components';
+export { searchPlugin, searchPlugin as plugin, SearchPage } from './plugin';
+export {
+  Filters,
+  FiltersButton,
+  SearchBar,
+  SearchPage as Router,
+  SearchResult,
+  SidebarSearch,
+} from './components';
+export type { FiltersState } from './components';

plugins/search/src/plugin.test.ts

@@ -13,10 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { plugin } from './plugin';
+import { searchPlugin } from './plugin';
 
 describe('search', () => {
   it('should export plugin', () => {
-    expect(plugin).toBeDefined();
+    expect(searchPlugin).toBeDefined();
   });
 });

plugins/search/src/plugin.ts

@@ -13,17 +13,31 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createPlugin, createRouteRef } from '@backstage/core';
-import { SearchPage } from './components/SearchPage';
+import {
+  createPlugin,
+  createRouteRef,
+  createRoutableExtension,
+} from '@backstage/core';
+import { SearchPage as SearchPageComponent } from './components/SearchPage';
 
 export const rootRouteRef = createRouteRef({
   path: '/search',
   title: 'search',
 });
 
-export const plugin = createPlugin({
+export const searchPlugin = createPlugin({
   id: 'search',
   register({ router }) {
-    router.addRoute(rootRouteRef, SearchPage);
+    router.addRoute(rootRouteRef, SearchPageComponent);
+  },
+  routes: {
+    root: rootRouteRef,
   },
 });
+
+export const SearchPage = searchPlugin.provide(
+  createRoutableExtension({
+    component: () => import('./components/SearchPage').then(m => m.SearchPage),
+    mountPoint: rootRouteRef,
+  }),
+);

plugins/techdocs/dev/index.tsx

@@ -16,7 +16,7 @@
 
 import { configApiRef, discoveryApiRef } from '@backstage/core';
 import { createDevApp } from '@backstage/dev-utils';
-import { plugin } from '../src/plugin';
+import { techdocsPlugin } from '../src/plugin';
 import { TechDocsDevStorageApi } from './api';
 import { techdocsStorageApiRef } from '../src';
 
@@ -30,5 +30,5 @@ createDevApp()
         discoveryApi,
       }),
   })
-  .registerPlugin(plugin)
+  .registerPlugin(techdocsPlugin)
   .render();

plugins/techdocs/src/Router.tsx

@@ -16,6 +16,7 @@
 
 import React from 'react';
 import { Entity } from '@backstage/catalog-model';
+import { useEntity } from '@backstage/plugin-catalog-react';
 import { Route, Routes } from 'react-router-dom';
 import { MissingAnnotationEmptyState } from '@backstage/core';
 import {
@@ -38,7 +39,14 @@ export const Router = () => {
   );
 };
 
-export const EmbeddedDocsRouter = ({ entity }: { entity: Entity }) => {
+type Props = {
+  /** @deprecated The entity is now grabbed from context instead */
+  entity?: Entity;
+};
+
+export const EmbeddedDocsRouter = (_props: Props) => {
+  const { entity } = useEntity();
+
   const projectId = entity.metadata.annotations?.[TECHDOCS_ANNOTATION];
 
   if (!projectId) {

plugins/techdocs/src/api.ts

@@ -157,14 +157,23 @@ export class TechDocsStorageApi implements TechDocsStorage {
       `${url.endsWith('/') ? url : `${url}/`}index.html`,
     );
 
-    if (request.status === 404) {
-      let errorMessage = 'Page not found. ';
-      // path is empty for the home page of an entity's docs site
-      if (!path) {
-        errorMessage +=
-          'This could be because there is no index.md file in the root of the docs directory of this repository.';
-      }
-      throw new Error(errorMessage);
+    let errorMessage = '';
+    switch (request.status) {
+      case 404:
+        errorMessage = 'Page not found. ';
+        // path is empty for the home page of an entity's docs site
+        if (!path) {
+          errorMessage +=
+            'This could be because there is no index.md file in the root of the docs directory of this repository.';
+        }
+        throw new Error(errorMessage);
+      case 500:
+        errorMessage =
+          'Could not generate documentation or an error in the TechDocs backend. ';
+        throw new Error(errorMessage);
+      default:
+        // Do nothing
+        break;
     }
 
     return request.text();

plugins/techdocs/src/index.ts

@@ -14,7 +14,12 @@
  * limitations under the License.
  */
 
-export { plugin } from './plugin';
+export {
+  techdocsPlugin,
+  techdocsPlugin as plugin,
+  TechdocsPage,
+  EntityTechdocsContent,
+} from './plugin';
 export { Router, EmbeddedDocsRouter } from './Router';
 export * from './reader';
 export * from './api';

plugins/techdocs/src/plugin.test.ts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 
-import { plugin } from './plugin';
+import { techdocsPlugin } from './plugin';
 
 describe('techdocs', () => {
   it('should export plugin', () => {
-    expect(plugin).toBeDefined();
+    expect(techdocsPlugin).toBeDefined();
   });
 });

plugins/techdocs/src/plugin.ts

@@ -35,6 +35,7 @@ import {
   createApiFactory,
   configApiRef,
   discoveryApiRef,
+  createRoutableExtension,
 } from '@backstage/core';
 import {
   techdocsStorageApiRef,
@@ -58,7 +59,7 @@ export const rootCatalogDocsRouteRef = createRouteRef({
   title: 'Docs',
 });
 
-export const plugin = createPlugin({
+export const techdocsPlugin = createPlugin({
   id: 'techdocs',
   apis: [
     createApiFactory({
@@ -80,4 +81,22 @@ export const plugin = createPlugin({
         }),
     }),
   ],
+  routes: {
+    root: rootRouteRef,
+    entityContent: rootCatalogDocsRouteRef,
+  },
 });
+
+export const TechdocsPage = techdocsPlugin.provide(
+  createRoutableExtension({
+    component: () => import('./Router').then(m => m.Router),
+    mountPoint: rootRouteRef,
+  }),
+);
+
+export const EntityTechdocsContent = techdocsPlugin.provide(
+  createRoutableExtension({
+    component: () => import('./Router').then(m => m.EmbeddedDocsRouter),
+    mountPoint: rootCatalogDocsRouteRef,
+  }),
+);

plugins/techdocs/src/reader/components/Reader.tsx

@@ -155,7 +155,9 @@ export const Reader = ({ entityId, onReady }: Props) => {
   ]);
 
   if (error) {
-    return <TechDocsNotFound errorMessage={error.message} />;
+    // TODO Enhance API call to return customize error objects so we can identify which we ran into
+    // For now this defaults to display error code 404
+    return <TechDocsNotFound statusCode={404} errorMessage={error.message} />;
   }
 
   return (

plugins/techdocs/src/reader/components/TechDocsNotFound.test.tsx

@@ -41,3 +41,20 @@ describe('<TechDocsNotFound errorMessage="This is a custom error message" />', (
     expect(rendered.getByTestId('go-back-link')).toBeDefined();
   });
 });
+
+describe('<TechDocsNotFound statusCode={500} errorMessage="This is a custom error message" />', () => {
+  it('should render with a custom status code, custom error message and go back link', () => {
+    const rendered = render(
+      wrapInTestApp(
+        <TechDocsNotFound
+          statusCode={500}
+          errorMessage="This is a custom error message"
+        />,
+      ),
+    );
+    rendered.getByText(/This is a custom error message/i);
+    rendered.getByText(/500/i);
+    rendered.getByText(/Looks like someone dropped the mic!/i);
+    expect(rendered.getByTestId('go-back-link')).toBeDefined();
+  });
+});

plugins/techdocs/src/reader/components/TechDocsNotFound.tsx

@@ -19,9 +19,10 @@ import { ErrorPage, useApi, configApiRef } from '@backstage/core';
 
 type Props = {
   errorMessage?: string;
+  statusCode?: number;
 };
 
-export const TechDocsNotFound = ({ errorMessage }: Props) => {
+export const TechDocsNotFound = ({ errorMessage, statusCode }: Props) => {
   const techdocsBuilder = useApi(configApiRef).getOptionalString(
     'techdocs.builder',
   );
@@ -37,7 +38,7 @@ export const TechDocsNotFound = ({ errorMessage }: Props) => {
 
   return (
     <ErrorPage
-      status="404"
+      status={statusCode ? statusCode.toString() : '404'}
       statusMessage={errorMessage || 'Documentation not found'}
       additionalInfo={additionalInfo}
     />