jira-dashboard-backend

Jira Dashboard Backend

A plugin that makes requests to Atlassian REST API to get issues and project information from Jira.

The frontend plugin that displays this information is Jira Dashboard.

Setup

The following sections will help you get the Jira Dashboard Backend plugin setup and running.

Installation

Install the plugin by following the example below:

# From your Backstage root directory
yarn --cwd packages/backend add @axis-backstage/plugin-jira-dashboard-backend

Configuration

The Jira Dashboard plugin requires the following YAML to be added to your app-config.yaml:

jiraDashboard:
  token: ${JIRA_TOKEN}
  baseUrl: ${JIRA_BASE_URL}
  userEmailSuffix: ${JIRA_EMAIL_SUFFIX} # Optional
  annotationPrefix: ${JIRA_ANNOTATION_PREFIX} # Optional

Configuration Details:

• JIRA_TOKEN: The "Authorization" header used for Jira authentication.

  Note: The JIRA_TOKEN variable from Roadie's Backstage Jira plugin can not be reused here because of the added encoding in this token.

• JIRA_BASE_URL: The base url for Jira in your company, including the API version. For instance: https://jira.se.your-company.com/rest/api/2/
• JIRA_EMAIL_SUFFIX: Optional email suffix used for retrieving a specific Jira user in a company. For instance: @your-company.com. If not provided, the user entity profile email is used instead.
• JIRA_ANNOTATION_PREFIX: Optional annotation prefix for retrieving a custom annotation. Defaut value is jira.com. If you want to configure the plugin to be compatible with Roadie's Backstage Jira Plugin, use the following annotation prefix:

jiraDashboard:
   {/* required configs... */}
  annotationPrefix: jira

Authentication examples and trouble shooting

Either "Basic Auth" or "Personal Acccess Tokens" can be used.

This plugin will directly take the content of the "jiraDashboard.token" config string and use as the "Authorization" header in all Jira REST API calls.

Basic Auth example

To use "Basic Auth" for authentication you need to create the "Authentication" header. See the Jira documentation how to create and encode the token. This is the how to use the example token from the documentation (ZnJlZDpmcmVk) with curl.

curl -D- \
   -X GET \
   -H "Authorization: Basic ZnJlZDpmcmVk" \
   -H "Content-Type: application/json" \
   "https://your-domain.atlassian.net/rest/api/2/project/BS"

This would result in the following Backstage configuration:

jiraDashboard:
  token: Basic ZnJlZDpmcmVk
  baseUrl: https://your-domain.atlassian.net/rest/api/2/
  userEmailSuffix: ${JIRA_EMAIL_SUFFIX}

Personal Acccess Tokens example

See the Personal Acccess Tokens documentation how to use and create a PAT. The generated token can be directly used, there is no need to encode it. Using curl with a PAT.

curl -D- \
   -X GET \
   -H "Authorization: Bearer <Token>" \
   -H "Content-Type: application/json" \
   "https://your-domain.atlassian.net/rest/api/2/project/BS"

And the corresponding Backstage configuration:

jiraDashboard:
  token: Bearer <Token>
  baseUrl: https://your-domain.atlassian.net/rest/api/2/
  userEmailSuffix: ${JIRA_EMAIL_SUFFIX}

Integrating

Here's how to get the backend plugin up and running:

1. Create a new file named packages/backend/src/plugins/jiraDashboard.ts, and add the following to it:

   import { createRouter } from '@axis-backstage/plugin-jira-dashboard-backend';
   import { Router } from 'express';
   import { PluginEnvironment } from '../types';
   
   export default async function createPlugin(
     env: PluginEnvironment,
   ): Promise<Router> {
     return await createRouter({
       logger: env.logger,
       config: env.config,
       discovery: env.discovery,
       identity: env.identity,
       tokenManager: env.tokenManager,
     });
   }

2. Wire this into the overall backend router by adding the following to packages/backend/src/index.ts:

   import jiraDashboard from './plugins/jiraDashboard';
   ...
   
   async function main() {
     // Add this line under the other lines that follow the useHotMemoize pattern
    const jiraDashboardEnv = useHotMemoize(module, () => createEnv('jira-dashboard'),
   
     // Add this under the lines that add their routers to apiRouter
    apiRouter.use('/jira-dashboard', await jiraDashboard(jiraDashboardEnv));
   }

3. Now run yarn start-backend from the repo root.

4. In another terminal, run the command: curl localhost:7007/api/jira-dashboard/health. The request should return {"status":"ok"}.

New Backend System

The Jira Dashboard backend plugin has support for the new backend system. Here is how you can set it up:

In your packages/backend/src/index.ts make the following changes:

const backend = createBackend();
+ backend.add(import('@axis-backstage/plugin-jira-dashboard-backend'));
// ... other feature additions

backend.start();