Update plugin sonarqube-backend's README with proper information

Signed-off-by: Neemys <36508659+Neemys@users.noreply.github.com>
2022-07-22 16:45:27 +02:00
parent ddd47ff7fb
commit 648190c0b4
1 changed files with 132 additions and 6 deletions
@@ -2,12 +2,138 @@

 Welcome to the sonarqube-backend backend plugin!

-_This plugin was created through the Backstage CLI_
+## Integrating into a backstage instance

-## Getting started
+This plugin needs to be added to an existing backstage instance.

-Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/sonarqube-backend](http://localhost:3000/sonarqube-backend).
+```bash
+# From your Backstage root directory
+yarn add --cwd packages/backend @backstage/plugin-sonarqube-backend
+```

-You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
-This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
-It is only meant for local development, and the setup for it can be found inside the [/dev](/dev) directory.
+Typically, this means creating a `src/plugins/sonarqube.ts` file and adding a reference to it to `src/index.ts` in the backend package.
+
+### sonarqube.ts
+
+```typescript
+import {
+  createRouter,
+  DefaultSonarqubeInfoProvider,
+} from '@backstage/plugin-sonarqube-backend';
+import { Router } from 'express';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  return await createRouter({
+    logger: env.logger,
+    sonarqubeInfoProvider: DefaultSonarqubeInfoProvider.fromConfig(env.config),
+  });
+}
+```
+
+### src/index.ts
+
+```diff
+diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts
+index 1942c36ad1..7fdc48ba24 100644
+--- a/packages/backend/src/index.ts
+++ b/packages/backend/src/index.ts
+@@ -50,6 +50,7 @@ import scaffolder from './plugins/scaffolder';
+ import proxy from './plugins/proxy';
+ import search from './plugins/search';
+ import techdocs from './plugins/techdocs';
+import sonarqube from './plugins/sonarqube';
+ import techInsights from './plugins/techInsights';
+ import todo from './plugins/todo';
+ import graphql from './plugins/graphql';
+@@ -133,6 +134,7 @@ async function main() {
+     createEnv('tech-insights'),
+   );
+   const permissionEnv = useHotMemoize(module, () => createEnv('permission'));
+  const sonarqubeEnv = useHotMemoize(module, () => createEnv('sonarqube'));
+
+   const apiRouter = Router();
+   apiRouter.use('/catalog', await catalog(catalogEnv));
+@@ -152,6 +154,7 @@ async function main() {
+   apiRouter.use('/badges', await badges(badgesEnv));
+   apiRouter.use('/jenkins', await jenkins(jenkinsEnv));
+   apiRouter.use('/permission', await permission(permissionEnv));
+  apiRouter.use('/sonarqube', await sonarqube(sonarqubeEnv));
+   apiRouter.use(notFoundHandler());
+
+   const service = createServiceBuilder(module)
+
+```
+
+This plugin must be provided with a `SonarqubeInfoProvider`, this is a strategy object for finding sonarqube instances in configuration and retrieving data from an instance.
+
+There is a standard one provided (`DefaultSonarqubeInfoProvider`), but the Integrator is free to build their own.
+
+### DefaultSonarqubeInfoProvider
+
+Allows configuration of either a single or multiple global Sonarqube instances and annotating entities with the instance name. This instance name in the entities is optional, if not provided the default instance in configuration will be used. That allow to keep configuration from before multiple instances capability to keep working without changes.
+
+#### Example - Single global instance
+
+##### Config
+
+```yaml
+sonarqube:
+  baseUrl: https://sonarqube.example.com
+  apiKey: 123456789abcdef0123456789abcedf012
+```
+
+##### Catalog
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backstage
+  annotations:
+    sonarqube.org/project-key: YOUR_INSTANCE_NAME/YOUR_PROJECT_KEY
+```
+
+#### Example - Multiple global instance
+
+The following will look for findings at `https://special-project-sonarqube.example.com` for the project of key `YOUR_PROJECT_KEY`.
+
+##### Config
+
+```yaml
+sonarqube:
+  instances:
+    - name: default
+      baseUrl: https://default-sonarqube.example.com
+      apiKey: 123456789abcdef0123456789abcedf012
+    - name: specialProject
+      baseUrl: https://special-project-sonarqube.example.com
+      apiKey: abcdef0123456789abcedf0123456789ab
+```
+
+##### Catalog
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backstage
+  annotations:
+    sonarqube.org/project-key: specialProject/YOUR_PROJECT_KEY
+```
+
+If the `specialProject/` part is omitted (or replaced with `default/`), the sonarqube instance of name `default` will be used.
+
+The following config is an equivalent (but less clear) version of the above:
+
+```yaml
+sonarqube:
+  baseUrl: https://default-sonarqube.example.com
+  apiKey: 123456789abcdef0123456789abcedf012
+  instances:
+    - name: specialProject
+      baseUrl: https://special-project-sonarqube.example.com
+      apiKey: abcdef0123456789abcedf0123456789ab
+```