Skip to main content
On-premise

Integrating CodeScene On-Premise with Jira

Integrating CodeScene with a project management (PM) tool like Jira allows you to retrieve cost and work type trends from your projects. This data is used to allocate costs to hotspots and detect trends in delivery performance, such as:

  • Planned vs Unplanned costs

  • Batch sizes

  • Delivery lead times

Below is a step-by-step guide to set up the Jira integration in CodeScene, followed by where to find the results, how CodeScene links commits to Jira issues, and how to troubleshoot common problems.

Before you start

Make sure that:

  • Your Jira issue keys (for example ABC-123) are included in commit messages, branch names or pull requests. CodeScene can only use Jira data for issues that are linked to commits.

  • You have a Jira user or API token with permission to read issues and their fields in every Jira project you want to connect.

⚠️ Note: PM integration is a CodeScene Pro feature.

1. Navigate to PM Data Integration

  1. Go to your Project Configuration in CodeScene.

  2. Click on the PM Data Integration.

2. Select Jira

  1. From the list of available PM tools, select Jira.

  2. Enter the Jira API URL.

    • Example: https://arnelacs.atlassian.net

3. Enter Jira API Credentials

Jira Cloud

  • Jira API Credentials: Enter your Jira user email address.

  • Jira API Password: Enter your Jira API token.

Jira Server

  • Jira API Credentials: Enter your Jira username. Leave blank if using a Personal Access Token.

  • Jira API Password: Enter your Jira password or Personal Access Token.

💡 Tip: CodeScene recommends using an API token rather than a password.

Which permissions does the token need?

CodeScene only reads data from Jira. It retrieves the issue fields created, updated, labels, issuetype and status, plus an optional cost field if you configure one. No comments, attachments or other issue details are retrieved. See Which Information is Retrieved from Jira.

Scoped (read-only) API tokens: From CodeScene 7.5.11, scoped Jira API tokens work with Jira Cloud integrations. If you use an older On-prem version and a scoped token fails, upgrade CodeScene or use a classic (unscoped) API token.

4. Create a Jira API Token

Follow these steps to generate a new API token in Jira:

  1. Click your profile image in the top-right corner → Account Settings.

  2. Navigate to:
    Atlassian account settings → Security → API tokens

  3. Click Create and manage API tokens → Create API token.

  4. Enter a descriptive name, e.g., CodeScene Integration.

  5. Under Expires on, select an expiration date.
    ⚠️ Note: Tokens cannot exceed 365 days.

  6. Click Create.

  7. Copy your API token and store it securely (e.g., in a password manager). You won’t be able to view it again.

💡 Tip: Make a note of the expiry date. When the token expires, CodeScene can no longer fetch Jira data. See Update an expired token below.

5. Select Cost Unit

  • Choose the unit used for your costs in the integration setup:

    • Issues, Estimated development time (cycle time based), Points, Minutes.

6. Configure Additional Options

Depending on your Jira setup, you may want to enable:

Use Labels as Work Types

If your Jira issue types don't reflect work types, you can use labels instead.

Map Subtasks to Parent Issues

If commits reference subtasks but you want analysis at the parent issue level, enable this. This ensures PM data and change coupling analysis happen on the parent issue. See What Does the 'Map Subtasks to Parent Issues' Option Do? for how the mapping works.

Map Commits to Pull Request Issues

Use issues referenced in Pull Requests containing analyzed commits. This requires the Pull Request integration to be configured. See How CodeScene links commits to Jira issues below.

7. Verify Credentials and Fetch Data

  1. Click Update and Continue.

  2. If a second page appears, your credentials are correct, and CodeScene successfully fetched data.

8. Configure External Projects

Under the External Projects field, a list of available Jira projects will be displayed. Select the relevant projects you want to integrate with CodeScene.

If a project you expect is missing from the list, the Jira account behind your token probably can't access it. See Troubleshooting.

Confirm that the following fields are correctly fetched from Jira:

  • Work In Progress Transition Names – The transition that indicates work is in progress.

  • Work Done Transition Names – The transition that indicates work is completed.

  • Defect Work Types – The work types used to identify defects. By default, CodeScene treats "Bug/Defect" as unplanned work. See What is Considered Unplanned Work?

If any of these fields are incorrect or incomplete, update them to match your Jira configuration.

💡 Tip: If different Jira projects use different workflows or transition names, you can add multiple detailed configurations.

Additional Optional Settings

  • Rename Work Types – Map work types to different names.

  • Cost Field – Specify which field represents cost.

  • Project Aliases – Map project aliases used on commits to PM project keys if they differ.

9. Submit and Re-run Analysis

  1. Click Submit to save your configuration.

  2. Re-run the analysis.

⚠️ Note: It may take a few days for enough data to accumulate before CodeScene stops reporting errors and showing the actual data. On the Analysis Results Dashboard, you can switch the timeframe to W (week) to see updated results sooner than at the monthly level.

10. Where to find your Jira data in CodeScene

After the next analysis, Jira data appears in these places:

  • Delivery: the project's Delivery tab shows the delivery KPIs Unplanned Work, Development Time and Pending Work per Developer.

    • Unplanned Work is the share of time spent on unplanned tasks, such as bugs, out of the time spent on all tasks.

    • Development Time is the average lead time per task, from In Progress to the last commit that references the task.

  • Hotspots: Defects and Costs on the hotspot map are calculated from your Jira data.

Good to know:

  • An issue only appears in Delivery if at least one commit is linked to it.

  • Delivery metrics such as cycle time and lead time require Work In Progress transition names to be configured.

  • Pending work is currently identified on the main analysis branch only.

  • After the first full fetch, CodeScene caches Jira data and only fetches issues updated since the last analysis.

For details, see Measure Development Outcomes in the CodeScene documentation.

How CodeScene links commits to Jira issues

CodeScene connects Jira issues to your code by finding issue keys (for example ABC-123) in one of these places:

  • The commit message, for example ABC-123 Fix login timeout. This is the most common setup and works with Jira smart commits.

  • The branch name, for example abc-123-fix-login-timeout.

  • The pull request: with Map Commits to Pull Request Issues enabled, CodeScene asks your Git provider which commits belong to each PR, and links them to the issues referenced in that PR.

When PM integration is enabled, the Ticket ID Pattern is created automatically to match your Jira project keys. If your commits use a different project key or alias, add it under Project Aliases.

⚠️ Note: If the Ticket ID Pattern isn't editable, it's because PM integration is enabled. To change it, disable PM integration, change the ticket ID mapping, then re-enable PM integration. See What to Do When the Ticket ID Pattern Does Not Match Jira Tickets.

💡 Tip: Branch-based or PR-based linking suits teams whose merge process rewrites or squashes commit messages, because the issue key may not survive in the final commit message.

Troubleshooting

Credentials are rejected, or no second configuration page appears

  • Check that Jira API Credentials is the email address of the account that owns the token (Jira Cloud) or your username (Jira Server).

  • Check that the token hasn't expired. Jira Cloud tokens last at most 365 days.

  • Check that the Jira API URL is correct, for example https://your-company.atlassian.net.

A scoped or read-only token fails with a 404 error

  • Older CodeScene versions didn't support Atlassian's scoped API tokens, and Jira Cloud returns 404 Not Found instead of an access error when a token can't reach a resource. Scoped tokens work from CodeScene 7.5.11. On older On-prem versions, upgrade or use a classic (unscoped) API token.

Some Jira projects show no data, or are missing from External Projects

This usually means the Jira account behind the token can't access those projects.

  1. Log in to Jira as the account used by CodeScene and check that you can open the affected projects and their issues.

  2. Grant the account access where needed.

  3. Run a new analysis. Once access is fixed, the data appears on the next analysis.

⚠️ Note: Before CodeScene 7.5.9, Jira could silently skip projects the token couldn't access, so PM data went missing without an error. From 7.5.9, CodeScene reports this as an error instead. If you run CodeScene On-prem, make sure you're on 7.5.9 or later.

Delivery shows "Not available", or a Delivery Performance warning

  • Check that Work In Progress Transition Names and Work Done Transition Names exactly match the transitions used in your Jira workflow.

  • Check that your commits reference Jira issue keys. See How CodeScene links commits to Jira issues.

  • If you've just set up the integration, allow time for data to accumulate, and try the W (week) timeframe.

Update an expired token

To update an expired token or other credentials, use Update configuration in the PM integration settings. This reloads the PM data used in the analysis.

Timeout errors during PM analysis

Large Jira instances can exceed the default 30-second timeout. Set the environment variable PM_DATA_TIMEOUT_MS to a larger value, for example 60000. See How to Handle a Timeout Error During PM Analyses?.

This setup will enable CodeScene to correlate code hotspots with project costs and work type trends, giving you actionable insights into your delivery performance.

Still need help? Ask the team