Setup & Installation - Spotify for Backstage

Prerequisites

Backend-to-backend authentication

Backend-to-backend authentication lets backend code in Backstage securely verify that a given request originates from another part of the backend, rather than from a user. This is useful for tasks like indexing catalog entities for search. This type of request shouldn’t be permissioned, so this feature must be enabled before turning on permissions. To set up backend-to-backend authentication, follow the setup instructions in the backstage.io docs.

User entities

Skill Exchange depends on user entities being present in the catalog, as users’ skill profiles are tied to these. Backstage has catalog modules to import users from GitHub, LDAP, or Azure AD. You can also define users in entity YAML files manually, or create a custom EntityProvider. In order for Skill Exchange to properly identify the user entity associated with the currently signed-in user, the SignInResolver must issue an identity token with a sub (subject) claim that is an entity ref to the user entity in the catalog corresponding to the signed-in user. Many authentication providers already provide this behavior, but if using a custom provider, you may need to add this behavior yourself. For examples, see the Google auth sign-in resolver or the GitHub auth sign-in resolver. For information on configuring a sign-in resolver, see the identity resolver docs on backstage.io.

Notifications

Skill Exchange supports notifications via Backstage’s notification plugin. While optional, notifications are recommended to reap the full benefits of Skill Exchange by keeping you informed of requests, connections, and updates. For detailed setup instructions, see the Notifications documentation.

Backend Installation

Getting the plugin

Add the Skill Exchange packages as dependencies to your Backstage instance:

yarn workspace backend add @spotify/backstage-plugin-skill-exchange-backend @spotify/backstage-plugin-search-backend-module-skill-exchange

Integrate the plugin with your Backstage app

You can integrate the Skill Exchange backend plugin with your Backstage backend. You just need to add the following:

packages/backend/src/index.ts

import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

backend.add(import('@backstage/plugin-app-backend/alpha'));
backend.add(import('@spotify/backstage-plugin-skill-exchange-backend'));
backend.add(
  import('@spotify/backstage-plugin-search-backend-module-skill-exchange'),
);
// ...

backend.start();

[Optional] Skill Exchange Actions

Skill Exchange provides actions that integrate with Backstage’s Actions Registry, enabling programmatic discovery of skills and experts. To install:

packages/backend/src/index.ts

backend.add(
  import('@spotify/backstage-plugin-skill-exchange-backend-module-actions'),
);

For detailed documentation on available actions and usage examples, see the Actions page.

Legacy Backend

If you are still using the Legacy Backend you can follow these instructions but we highly recommend migrating to the New Backend System.

Create a new file, packages/backend/src/plugins/skillexchange.ts with the following content:

packages/backend/src/plugins/skillexchange.ts

import { Router } from 'express';
import { PluginEnvironment } from '../types';
import { createRouter } from '@spotify/backstage-plugin-skill-exchange-backend';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  return await createRouter({
    ...env,
  });
}

Wire up the Skill Exchange backend in packages/backend/src/index.ts. You’ll need to import the module from the previous step, create a plugin environment, and add the router to the express app:

packages/backend/src/index.ts

import proxy from './plugins/proxy';
import techdocs from './plugins/techdocs';
import search from './plugins/search';
import permission from './plugins/permission';
import skillexchange from './plugins/skillexchange';

/* ... */

const techdocsEnv = createEnv('techdocs');
const searchEnv = createEnv('search');
const appEnv = createEnv('app');
const permissionEnv = createEnv('permission');
const skillexchangeEnv = createEnv('skillEx');

/* ... */

apiRouter.use('/techdocs', await techdocs(techdocsEnv));
apiRouter.use('/proxy', await proxy(proxyEnv));
apiRouter.use('/search', await search(searchEnv));
apiRouter.use('/permission', await permission(permissionEnv));
apiRouter.use('/skill-exchange', await skillexchange(skillexchangeEnv));

Add the SkillProfileDecoratorFactory to the search plugin in packages/backend/src/search.ts. This decorates user entities with the skills they add to their profiles and allows them to be found via search.

packages/backend/src/search.ts

import { SkillProfileDecoratorFactory } from '@spotify/backstage-plugin-skill-exchange-backend';

export default async function createPlugin({
  cache,
  logger,
  permissions,
  discovery,
  config,
}: PluginEnvironment) {
  // Initialize a connection to a search engine.
  const searchEngine = new LunrSearchEngine({ logger });

  const indexBuilder = new IndexBuilder({ logger, searchEngine });

  indexBuilder.addDecorator({
    factory: SkillProfileDecoratorFactory.fromConfig(env.config, {
      cache: env.cache,
      discovery: env.discovery,
      logger: env.logger,
      tokenManager: env.tokenManager,
    }),
  });

  return await createRouter({
    engine: indexBuilder.getSearchEngine(),
    types: indexBuilder.getDocumentTypes(),
    permissions,
    config,
    logger,
  });
}

[Optional] Defining default lists

Skill Exchange has the ability to ingest lists of items that can be used across the application. For example, by adding a YAML list of locations, Gigs (Embeds, Mentorships, etc) can have their location to set to one of the locations defined in the YAML list. You can also define a default list of skills that users can select to add to their profiles. This list is defined in a YAML file and passed to the Skill Exchange plugin via configuration either as a local file path or a remote URL. You can add Skills, Locations, and Embed Priority Labels by creating a new yaml file using the following basic structure. Locations and embed priority labels are defined as a flat list of names. See Defining Skills for Ingestion below for more information on ingesting skills.

default-lists.yaml

# default-lists.yaml

skills:
  - name: Web
    category: DISCIPLINE
  - name: Backend
    category: DISCIPLINE
  - name: JavaScript
    category: LANGUAGES
    subset: SKILLS
    disciplines:
      - Web
      - Backend
  - name: API Development
    category: TECHNIQUES
    subset: SKILLS
    disciplines:
      - Backend

locations:
  - Stockholm
  - New York
  - London

embedPriorityLabels:
  - Tech Lead
  - Company Bet Lead

Then add the configuration option in your app-config.yaml (or equivalent) file. The files property is used for local files, and the remoteUrls property is used for remote files. The files property expects all listed files to use the $include keyword. Refer to Including Files for more information about the $include keyword.

app-config.yaml

skillExchange:
  defaultLists:
    files: # for local files, relative to the backend process
      - $include: /path/to/default-lists.yaml
    remoteUrls: # for remote files
      - https://github.com/org/repo/blob/main/default-lists.yaml

When using local files this is relative to the backend process.

You can have multiple YAML lists.You can have a different YAML file for skills and locations, and you can also have multiple files for the same type of data. For example, you can have a YAML file for locations in North America, and another YAML file for locations in Asia. The files property on defaultLists takes an array of paths to your YAML files. Similarly, the remoteUrls property takes an array of URLs to remote YAML files. For more information on remote URLs, see “Remote configuration options” under Defining Skills for Ingestion.

Ingestion runs when you next restart Backstage. Items are only added and not removed, and duplicates are auto-detected. Therefore, you can leave the configuration settings and restart the Backstage instance multiple times without duplicating items. Modifying the YAML file will allow you to add new default items later.

Defining Skills for Ingestion

Skills defined through YAML for ingestion are treated as the source of truth for all skills within Skill Exchange. Each skill can be defined with the following fields:

Field	Type	Description	Value
`name`	String	[Required] The name of the skill.
`category`	Enum	[Required] The category of the skill.	”DISCIPLINE” \| “LANGUAGES” \| “FRAMEWORKS” \| “INFRASTRUCTURE” \| “TECHNIQUES”
`subset`	Enum	[Optional] Subset of the skill. Not required for skills with category “DISCIPLINE”.	”SKILLS” \| “TOOLS”
`disciplines`	String[]	[Optional] List of disciplines the skill is associated with. Not required for skills with category “DISCIPLINE”.

Here is an extensive list of skills in YAML format to get you started. To start using these default skills out of the box, provide a link to these skills to the remote configuration portion of Skill Exchange as described below.

Remote configuration options

If you have integrations set up within your Backstage instance, you also have the option to specify a list of remote sources that you’d like Skill Exchange to periodically read from. Types of valid integration URLs that Skill Exchange supports are listed here. Skill Exchange will de-duplicate lists of both local and remote sources and ingest from all sources it points to within the defaultLists config. The cadence at which remote file updates can be polled for can be controlled by using the skillExchange.remoteFileUpdates.frequency field, which can take in a cron field:

app-config.yaml

skillExchange:
  remoteFileUpdates:
    frequency:
      cron: '0 0 * * *'

or a duration field, which follows this shape:

app-config.yaml

skillExchange:
  remoteFileUpdates:
    frequency:
      duration:
        days: 1

Adding a new Skill

To add a new skill, simply add a new entry to the skills list to the skills YAML file. The skill will be ingested the next time the Backstage instance is restarted.

Editing and Deleting a Skill

To update or delete a skill, this must be done through the database as we currently do not support editing or deleting skills through the YAML at the moment.

[Optional] Schedule Hack Digest Notifications

To schedule periodic notifications for hack updates (edits to the hack, or new comments) to users who follow hacks, specify a cron value in your app-config.yaml (or equivalent) file. This cron value dictates the frequency with which users will receive updates on their hacks, if any updates exist since the last updates were sent. See the example below:

skillExchange:
  # ...
  hackUpdateNotificationsCron: '0 17 * * 1'
  # ...

[Optional] Configure Admin Deletion Capabilities

Skill Exchange supports admin deletion capabilities, allowing designated administrators to remove hacks, hack events, embeds, mentorships, and mentorship events from the UI. This feature is useful for cleanup purposes. Admin users are configured via the skillExchange.admins.postCleanupAdmins configuration field which accepts a list of user entity references:

app-config.yaml

skillExchange:
  admins:
    postCleanupAdmins:
      - 'user:default/admin'
      - 'user:default/anotherAdmin'

When configured, admin users will see delete and archive buttons when viewing posts. The post owners retain their existing ability to delete their own content.

Frontend Installation

Getting the plugin

Add @spotify/backstage-plugin-skill-exchange as a dependency to packages/app

yarn workspace app add @spotify/backstage-plugin-skill-exchange

Install the Skill Exchange frontend

Wire up routing to the SkillExchangePage entry page in the App.tsx file and enable the features you intend to use via app-config.yaml.

packages/app/src/App.tsx

import { SkillExchangePage } from '@spotify/backstage-plugin-skill-exchange';

const routes = (
  <FlatRoutes>
    <Navigate key="/" to="catalog" />

    <Route path="/skill-exchange" element={<SkillExchangePage />} />
  </FlatRoutes>
);

app-config.yaml

skillExchange:
  # ...
  enableEmbeds: false
  enableMentorships: true
  enableHacks: true
  # ...

Add a sidebar menu item that routes to the path setup in the previous step:

packages/app/src/components/Root/Root.tsx

import SchoolIcon from '@material-ui/icons/School';

<SidebarScrollWrapper>
  <SidebarItem icon={MapIcon} to="tech-radar" text="Tech Radar" />
  <SidebarItem icon={SchoolIcon} to="skill-exchange" text="Skill Exchange" />
</SidebarScrollWrapper>;

Add the User entity skills card

Skill Exchange integration with the Backstage user pages is required in order to view and edit skill profiles. To enable, add the SkillExchangeUserEntitySkillsCard to the catalog user entity page:

packages/app/src/components/catalog/EntityPage.tsx

import { SkillExchangeUserEntitySkillsCard } from '@spotify/backstage-plugin-skill-exchange';

const userPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      <Grid container spacing={3}>
        {entityWarningContent}
        <Grid item xs={12} md={6}>
          <EntityUserProfileCard variant="gridItem" />
        </Grid>
        <Grid item xs={12} md={6}>
          <EntityOwnershipCard variant="gridItem" />
        </Grid>
        <Grid item xs={12} md={6}>
          <SkillExchangeUserEntitySkillsCard />
        </Grid>
      </Grid>
    </EntityLayout.Route>
  </EntityLayout>
);

Up and running!

Skill Exchange is now up and running! Get started by clicking the link in your Backstage sidebar, or visiting <backstage-instance>/skill-exchange.

Available Permissions

The Skill Exchange plugin does not implement any permissions to restrict access to the plugin.

Documentation Index

​Prerequisites

​Backend-to-backend authentication

​User entities

​Sign-in resolver

​Notifications

​Backend Installation

​Getting the plugin

​Integrate the plugin with your Backstage app

​[Optional] Skill Exchange Actions

​Legacy Backend

​[Optional] Defining default lists

​Defining Skills for Ingestion

Remote configuration options

Adding a new Skill

Editing and Deleting a Skill

​[Optional] Schedule Hack Digest Notifications

​[Optional] Configure Admin Deletion Capabilities

​Frontend Installation

​Getting the plugin

​Install the Skill Exchange frontend

​Add the User entity skills card

​Up and running!

​Available Permissions

Prerequisites

Backend-to-backend authentication

User entities

Sign-in resolver

Notifications

Backend Installation

Getting the plugin

Integrate the plugin with your Backstage app

[Optional] Skill Exchange Actions

Legacy Backend

[Optional] Defining default lists

Defining Skills for Ingestion

[Optional] Schedule Hack Digest Notifications

[Optional] Configure Admin Deletion Capabilities

Frontend Installation

Getting the plugin

Install the Skill Exchange frontend

Add the User entity skills card

Up and running!

Available Permissions