Get Roadie in your IDE with our new MCP Servers
Roadie
← Backstage Plugins Guides
Jira logo

Backstage Jira Plugin

Created by Roadie

Jira is Atlassian’s flagship issue tracking and agile project management platform used by thousands of engineering teams worldwide to plan, track, and manage software development projects.

The Jira Backstage plugin brings tickets into Backstage by surfacing project information directly in your developer portal. Originally developed by Roadie and now widely adopted across the Backstage ecosystem, this plugin connects your Backstage entities to their corresponding Jira projects, providing real-time visibility into development progress without leaving your service catalog.

What the plugin provides

The plugin integrates seamlessly with both Jira Cloud and Server/Data Center instances to display:

  • Project overview and health metrics - See active issues, sprint progress, and project status at a glance
  • Issue tracking and lifecycle management - Track stories, bugs, and epics directly from your service pages
  • Activity streams and recent updates - Monitor project activity and stay informed of changes affecting your services
  • Custom JQL query results - Display filtered issue lists based on complex queries tailored to your team’s needs
  • Personal dashboards - View tickets assigned to you across all projects from your Backstage homepage

Why use this plugin

Developers can access Jira information directly alongside service documentation, dependencies, and deployment status in Backstage. This unified view reduces context switching and provides a complete picture of your service’s development lifecycle.

Major organizations like John Lewis & Partners have successfully integrated Jira data into their Backstage deployments, with John Lewis noting: “We use Backstage with data aggregated from key applications such as Gitlab, Pagerduty, JIRA, Kubecost and Google Cloud, serving that data via Big Query to specific Backstage panels.”

This guide covers installation for both Jira Cloud and Server instances, configuration options for single and multiple projects, and usage examples to help you get started quickly.

A preview of Jira plugin including tasks summary, project information and Activity Stream.

Installation Instructions

These instructions apply to self-hosted Backstage only. To use this plugin on Roadie, visit the docs.

Install the plugin into Backstage.

Copy 
yarn --cwd packages/app add @roadiehq/backstage-plugin-jira

Add proxy configuration to app-config.yaml

Copy 
# app-config.yaml
proxy:
  '/jira/api':
    target: '<JIRA_URL>'
    headers:
      Authorization: ${JIRA_TOKEN}
      Accept: 'application/json'
      Content-Type: 'application/json'
      X-Atlassian-Token: 'nocheck'
      User-Agent: "MY-UA-STRING"

jira:
  proxyPath: /jira/api
  product: cloud  # Use 'cloud' for Jira Cloud or 'datacenter' for Server/Data Center

Set img-src in Content Security Policy

Copy 
// app-config.yaml
backend:
  # ...
  csp:
    img-src: 
      # "'self'" and 'data' are from the backstage default but must be set since img-src is overriden
      - "'self'"
      - 'data:'
      # Allow your Jira instance for @roadiehq/backstage-plugin-jira
      - 'JIRA_URL'

Add plugin API to your Backstage instance

Copy 
// packages/app/src/components/catalog/EntityPage.tsx
import {
  EntityJiraOverviewCard,
  isJiraAvailable,
  hasJiraQuery,
  EntityJiraQueryCard,
} from '@roadiehq/backstage-plugin-jira';

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    <EntitySwitch>
      <EntitySwitch.Case if={isJiraAvailable}>
        <Grid item md={12}>
          <EntityJiraOverviewCard />
        </Grid>
      </EntitySwitch.Case>
      <EntitySwitch.Case if={hasJiraQuery}>
         <Grid item md={12}>
           {/* This card can be used as an alternative or in addition to the overview card */}
           <EntityJiraQueryCard title="Our Custom Query" />
         </Grid>
       </EntitySwitch.Case>
    </EntitySwitch>
  </Grid>
);

Add annotation to the yaml config file of a component

Copy 
metadata:
  annotations:
    # Find this in the project settings page
    jira/project-key: <example-jira-project-key>
    # optional, you might skip this value to fetch data for all components
    jira/component: <example-component> 
    # optional, used for Activity stream feed. If you are using Basic auth you can skip this.
    jira/token-type: Bearer 
    # optional, refine filter based on a label or labels (CSV)
    jira/label: <example-label> 
    # optional, used by EntityJiraQueryCard, this query supports basic templating with the above annotations if present, and information from the user profile. e.g. "assignee = {{ userEmail }} AND label = ({{ label }})"
    jira/all-issues-jql:

Even though you can use Bearer token please keep in mind that Activity stream feed will only contain entries that are visible to anonymous users. In order to view restricted content you will need to authenticate via Basic authentication, as described in official documentation.

Copy 
# Set your environment variable
export JIRA_TOKEN='Basic <your-base64-encoded-credentials>'

# Or run Backstage locally with the token
env JIRA_TOKEN='Basic <your-base64-encoded-credentials>' yarn dev

Things to Know

The plugin displays your Jira project information directly in the entity overview, showing issue counts, project details, and activity streams at a glance.

Plugin Components

The Jira plugin provides several UI components that you can add to your entity pages and homepage:

Overview Card

The EntityJiraOverviewCard displays essential project information:

  • Project name and key
  • Issue counts by status (To Do, In Progress, Done)
  • Recent project activity
  • Direct link to the Jira project dashboard

Query Card

The EntityJiraQueryCard allows custom JQL queries:

  • Displays results of custom JQL searches
  • Supports dynamic templating with entity annotations
  • Configurable title and query parameters
  • Useful for team-specific or filtered views
Copy 
import { EntityJiraQueryCard } from '@roadiehq/backstage-plugin-jira';

<Grid item md={6}>
  <EntityJiraQueryCard title="Critical Bugs" />
</Grid>

Homepage Component

The HomePageMyJiraTicketsCard shows personalized ticket information:

  • Open and In Progress tickets assigned to the current user
  • Quick access to your most relevant work items
  • Integrates with Backstage’s user profile system
Copy 
import { HomePageMyJiraTicketsCard } from '@roadiehq/backstage-plugin-jira';

<Grid item xs={12} md={6}>
  <HomePageMyJiraTicketsCard />
</Grid>

Required Annotations

To connect your Backstage entities to Jira projects, add specific annotations to your entity metadata:

Basic Project Mapping

For a single Jira project:

Copy 
metadata:
  annotations:
    jira/project-key: MYPROJ

Component-Specific Issues

To filter issues by Jira component:

Copy 
metadata:
  annotations:
    jira/project-key: MYPROJ
    jira/component: backend-service

Label-Based Filtering

Filter issues by labels (supports comma-separated values):

Copy 
metadata:
  annotations:
    jira/project-key: MYPROJ
    jira/label: microservice,backend

Custom JQL Queries

For advanced filtering with JQL (Jira Query Language):

Copy 
metadata:
  annotations:
    jira/project-key: MYPROJ
    jira/all-issues-jql: 'assignee = "{{ userEmail }}" AND status != "Done" AND project = "{{ projectKey }}"'

The JQL query supports templating with:

  • {{ userEmail }} - Current user’s email
  • {{ projectKey }} - The project key from annotations
  • {{ component }} - Component name from annotations
  • {{ label }} - Labels from annotations

Configuration Options

Single Jira Instance

For organizations using a single Jira instance:

Copy 
### app-config.yaml
proxy:
  '/jira/api':
    target: 'https://your-company.atlassian.net'
    headers:
      Authorization: ${JIRA_TOKEN}
      Accept: 'application/json'
      Content-Type: 'application/json'
      X-Atlassian-Token: 'nocheck'
      User-Agent: "Backstage-Jira-Plugin"

jira:
  proxyPath: /jira/api
  product: cloud

Authentication Setup

Obtaining a Jira API Token

  1. Visit Atlassian API Tokens
  2. Click “Create API token”
  3. Give it a descriptive name (e.g., “Backstage Integration”)
  4. Copy the generated token immediately (it won’t be shown again)

Creating the Authentication Header

  1. Create a base64-encoded string in the format:

    Copy 
    <your-atlassian-email>:<your-api-token>

    For example:

    Copy 
    [email protected]:hTBgqVcrcxRYpT5TCzTA9C0F

  2. Encode this string to base64:

    Copy 
    echo -n "[email protected]:hTBgqVcrcxRYpT5TCzTA9C0F" | base64

    Result:

    Copy 
    am9obi5kb2VAY29tcGFueS5jb206aFRCZ3FWY3JjeFJZcFQ1VEN6VEE5QzBG

  3. Set your environment variable with the Basic prefix:

    Copy 
    export JIRA_TOKEN='Basic am9obi5kb2VAY29tcGFueS5jb206aFRCZ3FWY3JjeFJZcFQ1VEN6VEE5QzBG'

Token Types and Activity Streams

For Activity Stream feeds, you can optionally specify the token type:

Copy 
metadata:
  annotations:
    jira/project-key: MYPROJ
    jira/token-type: Bearer  # Default is Basic

Note: Activity streams with Bearer tokens only show publicly visible content. For private or restricted content, use Basic authentication as described above.

Feature Flags

The plugin supports feature flags for optional functionality:

Linked Pull Requests

Enable the display of linked pull requests in issue views:

Copy 
### app-config.yaml
jira:
  # other config...
  featureFlags:
    showLinkedPRs: true

This feature is particularly useful for Jira Data Center instances and provides visibility into code changes associated with specific issues.

Troubleshooting

Common Issues

Plugin not displaying: Verify your entity has the correct jira/project-key annotation and that the project exists in your Jira instance.

Authentication errors: Check that your API token is valid. The user associated with the token should have read access to the projects you’re trying to display. Make sure the token is base64 encoded correctly.

CORS issues: Ensure your proxy configuration is correct and that the X-Atlassian-Token: 'nocheck' header is included.

Activity stream not showing: This typically indicates the content is private. Switch to Basic authentication or adjust your Jira project permissions.

Required Permissions

Your Jira user needs these permissions:

  • Browse Projects - View project details and issues
  • View Development Tools - See linked development information
  • Read Attachments - View issue attachments in activity streams

Performance Considerations

For large Jira projects, consider:

  • Using component or label filters to limit the number of issues displayed
  • Implementing custom JQL queries to show only relevant issues
  • Configuring appropriate caching headers in your proxy setup

Advanced Usage

Custom Activity Stream Integration

Configure the Activity Stream to show specific types of updates:

Copy 
metadata:
  annotations:
    jira/project-key: MYPROJ
    jira/component: api-service
    jira/label: critical,backend
    # This will show activity for critical backend issues in the api-service component

Dashboard Integration

Use the HomePageMyJiraTicketsCard component to create personalized dashboards:

Copy 
// packages/app/src/components/home/HomePage.tsx
import { HomePageMyJiraTicketsCard } from '@roadiehq/backstage-plugin-jira';

<Grid container>
  <Grid item xs={12} md={6}>
    <HomePageMyJiraTicketsCard />
  </Grid>
  {/* Other dashboard components */}
</Grid>

This provides developers with immediate visibility into their assigned work when they open Backstage, improving productivity and reducing the need to check multiple tools.

References

Set up Backstage in minutes with Roadie

Get a demo