Backstage Azure DevOps Wiki Search Plugin

Azure DevOps includes a project wiki that many teams use for runbooks, ADRs, onboarding guides, and team notes. Azure DevOps Wiki Search brings those pages into Backstage Search. It connects to Azure DevOps, reads wiki pages, then makes the titles and content searchable inside your portal. You get one search box for code catalog items, docs, and wiki knowledge.

The plugin runs in the Backstage search backend as a collator. It crawls one wiki or many, converts articles into search documents, then feeds them into the Backstage index. Search results point users back to the source wiki so they can read the full page. Errors during indexing surface in your backend logs so you can spot problems fast. This fits well for self hosted Backstage installs where Azure DevOps is already the home for team knowledge.

Common use cases include surfacing runbooks during incidents, finding standards and practices across teams, and helping new hires discover context without asking around. If your company keeps docs in Azure DevOps wikis, this plugin gives that content the same treatment as catalog entities and TechDocs inside Backstage. It is built for the new backend system in Backstage.

Install with the new backend system

Step 1

Add the backend module to your backend workspace.

Copy

yarn add --cwd packages/backend @mdude2314/backstage-plugin-search-backend-module-azure-devops-wiki

Step 2

Add config for the collator in your app config. Use one of these examples.

Multiple wikis

Copy

# app-config.yaml

azureDevOpsWikiCollator:
  baseUrl: https://my-azure-instance.com
  token: ${AZURE_TOKEN}
  wikis:
    - wikiIdentifier: Wiki-Identifier.wiki
      organization: MyOrganization
      project: MyProject
      titleSuffix: " - My Suffix"
    - wikiIdentifier: Wiki-Identifier2.wiki
      organization: MyOrganization
      project: MyProject
      titleSuffix: " - Suffix 2"

Single wiki

Copy

# app-config.yaml

azureDevOpsWikiCollator:
  baseUrl: https://my-azure-instance.com
  token: ${AZURE_TOKEN}
  wikiIdentifier: Wiki-Identifier.wiki
  organization: MyOrganization
  project: MyProject
  titleSuffix: " - My Suffix"

Step 3

Provide the Azure token to the backend process.

Example shell export

Copy

export AZURE_TOKEN=your_pat_value

Example backend dotenv file

Copy

# packages/backend/.env
AZURE_TOKEN=your_pat_value

Step 4

Copy

// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';
import { searchModuleAzureDevopsWikiCollator } from '@mdude2314/backstage-plugin-search-backend-module-azure-devops-wiki';

const backend = createBackend();

backend.add(searchModuleAzureDevopsWikiCollator());

backend.start();

The module will index wiki pages into the Backstage search engine. Errors will show in backend logs.

Optional add the search UI to your app

If your app already has a search page, skip this section.

Step 1

Add the search frontend packages to the app workspace.

Copy

yarn workspace app add @backstage/plugin-search @backstage/plugin-search-react @backstage/core-components @material-ui/core

Step 2

Add a route for the search page.

Copy

// packages/app/src/App.tsx
import React from 'react';
import { Route } from 'react-router';
import { FlatRoutes } from '@backstage/core-app-api';
import { SearchPage } from '@backstage/plugin-search';

export const App = () => (
  <FlatRoutes>
    {/* other routes */}
    <Route path="/search" element={<SearchPage />} />
  </FlatRoutes>
);

Step 3

Add a link to the sidebar so users can reach the search page.

Copy

// packages/app/src/components/Root/Root.tsx
import React from 'react';
import { Sidebar, SidebarItem } from '@backstage/core-components';
import SearchIcon from '@material-ui/icons/Search';

export const Root = () => (
  <Sidebar>
    {/* other items */}
    <SidebarItem icon={SearchIcon} to="search" text="Search" />
  </Sidebar>
);

Old backend system

This module targets the new backend system only. There is no support for the old backend system for this package. Upgrade your backend to the new system to use it.

Backstage Azure DevOps Wiki Search Plugin

Installation Instructions

Install with the new backend system

Step 1

Step 2

Step 3

Step 4

Optional add the search UI to your app

Step 1

Step 2

Step 3

Old backend system

Changelog

Set up Backstage in minutes with Roadie