diff --git a/.changeset/cold-phones-matter.md b/.changeset/cold-phones-matter.md new file mode 100644 index 0000000000..0168c583e6 --- /dev/null +++ b/.changeset/cold-phones-matter.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-azure-devops-backend': patch +--- + +Added documentation for setting up and running the Azure DevOps Backend plugin diff --git a/plugins/azure-devops-backend/README.md b/plugins/azure-devops-backend/README.md index 4b278572d8..f3ec4ddd82 100644 --- a/plugins/azure-devops-backend/README.md +++ b/plugins/azure-devops-backend/README.md @@ -4,7 +4,11 @@ Simple plugin that proxies requests to the [Azure DevOps](https://docs.microsoft ## Setup -The following values are read from the configuration file: +The following sections will help you get the Azure DevOps Backend plugin setup and running + +### Configuration + +The Azure DevOps plugin requires the following YAML to be added to your app-config.yaml: ```yaml azureDevOps: @@ -17,8 +21,51 @@ Configuration Details: - `host` and `token` can be the same as the ones used for the `integration` section - `AZURE_TOKEN` environment variable must be set to a [Personal Access Token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page) with read access to both Code and Build -- `organization` is your Azure DevOps Organization name or for Azure DevOps Server (on-premise) this will be your Collection name +- `organization` is your Azure DevOps Services (cloud) Organization name or for Azure DevOps Server (on-premise) this will be your Collection name + +### Up and Running + +Here's how to get the backend up and running: + +1. First we need to add the `@backstage/plugin-azure-devops-backend` package to your backend: + + ```sh + # From the Backstage root directory + cd packages/backend + yarn add @backstage/plugin-azure-devops-backend + ``` + +2. Then we will create a new file named `packages/backend/src/plugins/azure-devops.ts`, and add the + following to it: + + ```ts + import { createRouter } from '@backstage/plugin-azure-devops-backend'; + import { Router } from 'express'; + import type { PluginEnvironment } from '../types'; + + export default function createPlugin({ + logger, + config, + }: PluginEnvironment): Promise { + return createRouter({ logger, config }); + } + ``` + +3. Next we wire this into the overall backend router, edit `packages/backend/src/index.ts`: + + ```ts + import azureDevOps from './plugins/azuredevops'; + // ... + async function main() { + // ... + const azureDevOpsEnv = useHotMemoize(module, () => createEnv('azure-devops')); + apiRouter.use('/azure-devops', await azureDevOps(azureDevOpsEnv)); + ``` + +4. Now run `yarn start-backend` from the repo root +5. Finally open `http://localhost:7000/api/azure-devops/health` in a browser and it should return `{"status":"ok"}` ## Links +- [Frontend part of the plugin](https://github.com/backstage/backstage/tree/master/plugins/azure-devops) - [The Backstage homepage](https://backstage.io)