Jira Integration (Token)

Overview

Link your Jira projects to automatically create and update issues based on Backline Vulnerabilities and Remediations.

What You Can Do

With the Jira integration, Backline can:

Automatically create a Jira ticket for a remediation when its pull request is opened
Route each remediation ticket to the right Jira project based on the affected application or repository
Set the new ticket’s fields — priority, status, and more — from your Backline remediation field mapping
Cross-link any existing vulnerability Jira tickets to the new remediation ticket
Track remediation work in your team’s existing workflow

Prerequisites

Before connecting Jira, ensure you have:

A Jira Cloud instance
Ability to create a service account in your Jira Cloud domain
Access to generate API tokens
Your Atlassian Cloud ID

Connecting Jira

Create Service Account

Create a dedicated service account in your Jira Cloud domain.

Generate API Token

Generate an API token from the service account. Visit: https://id.atlassian.com/manage-profile/security/api-tokensAdd the needed scopes (Classic or Granular - see below), generate the token, and copy it.

Get Cloud ID

Retrieve your Atlassian Cloud ID. Follow the instructions at: https://support.atlassian.com/jira/kb/retrieve-my-atlassian-sites-cloud-id/

Navigate to Integrations

In Backline, go to the Integration Hub from the main menu.

Select Jira

Find and click on the Jira integration card.

Enter Credentials

Provide your connection details:

API Token: The token you generated in Step 2
Cloud ID: Your Atlassian Cloud ID from Step 3
Email Address: The email address of the service account used to generate the token

Verify Connection

Click Connect to verify your credentials. Once verified, you’ll move to the Configuration tab.

Backline supports Jira Cloud only.

API Token Scopes

When creating your API token, you can choose between Classic or Granular scopes:

Classic Scopes

read:jira-work
read:jira-user
write:jira-work

Granular Scopes

read:avatar:jira
read:board-scope:jira-software
read:comment:jira
read:comment.property:jira
read:custom-field-contextual-configuration:jira
read:field.default-value:jira
read:group:jira
read:issue:jira
read:issue-details:jira
read:issue-field-values:jira
read:issue-type:jira
read:issue-type.property:jira
read:issue-type-screen-scheme:jira
read:label:jira
read:project:jira
read:project-role:jira
read:project.component:jira-platform
read:screen-scheme:jira
read:screen-tab:jira
read:screenable-field:jira
read:sprint:jira-software
read:status:jira
read:user:jira
write:comment:jira
write:issue:jira

Configuring Projects

After connecting, you’ll need to configure which Jira projects Backline should use:

Select Jira Project

In the Configuration tab, choose a Jira Project from the list of available projects.

Choose Issue Type

Select the issue type you want Backline to create for remediation tickets in this project.

Map Fields

Once the issue type is chosen, the mandatory and optional fields from Jira appear. Map each Jira field to one of the following:

A value from Jira
A Backline remediation field (see below)
A manually entered value

The Backline remediation fields available for mapping are Remediation Status, Remediation Priority, Remediation Mode, Remediation Type, Remediation Title, Highest Severity, and Time to SLA. Map Jira fields such as Priority and Status to the matching Backline remediation field so Backline can set them on the tickets it creates.

Save Configuration

Complete the field mapping and save your project configuration.

Automatic Remediation Tickets

Backline creates Jira tickets at the remediation level — one ticket for a fix that may span several vulnerabilities. Backline does not create tickets for individual vulnerabilities.

When tickets are created

When Auto-Create Ticket is enabled, Backline creates a remediation ticket when a pull request is opened for the remediation. If the remediation already has a ticket, Backline does not create another one.

Ticket content

Each ticket is composed automatically from the remediation record and includes:

A short summary of the vulnerabilities addressed and the fix applied
Remediation details — title, type, mode, and priority
Impact — highest severity, number of affected vulnerabilities, affected application/service, and repository or image
A recommended action — review and merge the pull request
Links back to the Backline remediation and the pull request

On creation, Backline sets the ticket’s Jira fields from your field mapping (see Map Fields), and links any existing vulnerability Jira tickets on the remediation’s vulnerabilities to the new ticket.

Remediation tickets are created unassigned. Connect a messaging integration like Slack to be alerted if a ticket can’t be created after automatic retries.

Configuration

The Configuration tab — shown right after you connect — is where you set up automatic remediation tickets.

Auto-Create Ticket

Toggle Auto-Create Ticket on to let Backline create a ticket when a remediation’s pull request is opened. It is off by default: no remediation tickets are created until you enable it.

Global Ticket Title Template

Define the title format for the Jira tickets Backline creates, so titles stay consistent and easy to search. The default is:

[Backline] {remediation_title}

Combine free text with any of these tokens, in any order:

Token	Value
`{remediation_title}`	The remediation’s title in Backline
`{remediation_priority}`	The remediation’s priority (`P1`, `P2`, or `P3`)
`{app_name}`	The affected application’s name
`{remediation_status}`	The remediation’s status (e.g. `Pending Approval`, `Manual Fix`)
`{remediation_mode}`	The remediation’s mode (`Auto` or `Hybrid`)

A token with no value for a given remediation is dropped from the title without failing ticket creation.

Project routing

Remediation tickets are routed to a Jira project based on the affected application or repository:

Project Mapping — upload a CSV that maps each application or repository to a Jira project. Download the template (pre-filled with your known repositories and detected applications), fill in the jira_project_name column, and upload it. After upload, a preview lists every row with its resolved status; rows that fail validation — unknown identifier, Jira project not found, or missing/duplicate identifier — are flagged and skipped. You can also override specific Jira fields per row.
Default Jira Project — the fallback project for any application or repository not covered by the mapping. A Default Jira Project is required before the integration can be activated.

The CSV has four columns — jira_project_name, application, repository_url, and the optional field_overrides. Each row maps one Jira project to exactly one identifier — either an application or a repository_url, leaving the other blank:

jira_project_name,application,repository_url,field_overrides
PAYMENTS,payments-api,,
PLATFORM,,https://github.com/acme/platform-service,

Uploading a new mapping merges into the existing one — adding or updating rows — and never removes rows absent from the new file. Identifiers are stored by a stable internal ID, so renaming an application or repository later won’t break routing. The issue type for created tickets comes from the destination Jira project’s own default issue type, so no extra configuration is needed.

Overriding fields per repository or application

By default, every ticket a project creates uses that project’s field mapping. The optional field_overrides column lets a single repository or application set its own values for specific Jira fields, on top of the project mapping — for example, routing a repo’s tickets to a different component or parent epic, or giving one repo a higher priority. Leave the column blank to use the project’s field mapping unchanged. When set, it’s a JSON object keyed by the Jira field’s display name (exactly as it appears in the field mapping). Only the fields you list are overridden; everything else keeps the project default.

Field kind	Value format	Example
Single-value field (select, component, assignee, …)	the value’s display name	`{"Component":"Billing"}`
Multi-value field	an array of display names	`{"Components":["api","web"]}`
Parent	the parent issue’s Jira key (not its name)	`{"Parent":"BKLN-186"}`
Priority	an object mapping each remediation priority to a Jira priority	`{"Priority":{"P1":"Highest","P2":"High","P3":"Medium"}}`
Status	an object mapping each remediation status to a Jira status	`{"Status":{"PendingApproval":"In Review","ManualFix":"In Progress"}}`

Priority and Status are keyed because Backline maps them from the remediation’s own priority (P1/P2/P3) or status (PendingApproval, ManualFix) — so you provide a value per key, just like in the field-mapping UI. Because the value contains commas and quotes, wrap the whole JSON object in double quotes and double every inner quote (standard CSV escaping):

jira_project_name,application,repository_url,field_overrides
PAYMENTS,payments-api,,"{""Priority"":{""P1"":""Highest"",""P2"":""High""},""Component"":""Billing""}"
PLATFORM,,https://github.com/acme/platform-service,"{""Parent"":""BKLN-186""}"

All values are validated on upload against the destination project: each field name and value must resolve to a real Jira field and option. If any value is invalid — an unknown field, a value that isn’t a valid option, a parent key that doesn’t exist, or the wrong shape for the field — that row is flagged and skipped, and the rest of the upload is rejected, so a bad override never reaches ticket creation.

Managing the Integration

Managing Projects

To view and manage your connected Jira projects:

Open Project Management

From the Jira Integration card, click the three dots menu and choose Manage Project.

View Connected Projects

You’ll see all connected Jira projects listed.

Edit or Delete

For each connected project, you can:

Edit the configuration to modify field mappings or issue types
Delete the project to remove the connection

Add More Projects

Click Add Project to configure additional Jira projects.

Connect a messaging integration like Slack to receive notifications if there’s an issue connecting or updating a ticket during the remediation process.

Get Started

Settings

Integrations

Overview

What You Can Do

Prerequisites

Connecting Jira

API Token Scopes

Classic Scopes

Granular Scopes

Configuring Projects

Automatic Remediation Tickets

When tickets are created

Ticket content

Configuration

Auto-Create Ticket

Global Ticket Title Template

Project routing

Overriding fields per repository or application

Managing the Integration

Managing Projects

​Overview

​What You Can Do

​Prerequisites

​Connecting Jira

​API Token Scopes

​Classic Scopes

​Granular Scopes

​Configuring Projects

​Automatic Remediation Tickets

​When tickets are created

​Ticket content

​Configuration

​Auto-Create Ticket

​Global Ticket Title Template

​Project routing

​Overriding fields per repository or application

​Managing the Integration

​Managing Projects

Overview

What You Can Do

Prerequisites

Connecting Jira

API Token Scopes

Classic Scopes

Granular Scopes

Configuring Projects

Automatic Remediation Tickets

When tickets are created

Ticket content

Configuration

Auto-Create Ticket

Global Ticket Title Template

Project routing

Overriding fields per repository or application

Managing the Integration

Managing Projects