How Issue Keys are detected

Overview

Azure DevOps for Jira automatically associates development information with Jira issues by detecting Jira issue keys (for example, PROJ-123) from Azure DevOps events.

Issue keys can be extracted from a variety of locations depending on the type of development information being processed, including commits, branches, pull requests, builds, and deployments.

This guide describes all locations that are currently scanned for Jira issue keys.

Commits

Commit information is primarily processed from Git push events.

Issue keys can be detected from:

Location	Example
Commit message	`PROJ-123 Fixed authentication issue`
Branch name associated with the commit	`feature/PROJ-123-user-authentication`

Examples

Commit Message

CODE

PROJ-123 Fix login validation

Branch Name

CODE

feature/PROJ-123-login-validation

Branches

Branch information can be created from both Git push events and pull request activity.

Issue keys can be detected from:

Location	Example
Branch name	`feature/PROJ-123-login-validation`
Pull request source branch name	`feature/PROJ-123-login-validation`

Examples

CODE

feature/PROJ-123-login-validation
bugfix/PROJ-456-null-pointer-fix
release/PROJ-789-v2.0

Pull Requests

When pull requests are created, updated, or merged, Azure DevOps for Jira scans multiple pull request attributes for Jira issue keys.

Issue keys can be detected from:

Location	Example
Pull request title	`PROJ-123 Add OAuth support`
Pull request description	Contains `PROJ-123`
Commit messages included in the pull request	Commit references `PROJ-123`
Last merge commit message	Contains `PROJ-123`
Merge commit message specified during completion	Contains `PROJ-123`
Source branch name	`feature/PROJ-123-oauth-support`
Pull request event message	Contains `PROJ-123`

Examples

PR Title

CODE

PROJ-123 Add OAuth support

PR Description

CODE

Implements the remaining work for PROJ-123.

Source Branch

CODE

feature/PROJ-123-oauth-support

Builds

Build information can be generated from traditional build pipelines and YAML pipelines.

Issue keys can be detected from:

Location	Example
Commit messages included in the build	Commit references `PROJ-123`
Source branch	`feature/PROJ-123-login-validation`
CI trigger message	Contains `PROJ-123`
Source version information	References `PROJ-123`
Stage name	`Deploy PROJ-123`
Pipeline name	`PROJ-123 Build Pipeline`
Build event message	Contains `PROJ-123`
Build event detailed message	Contains `PROJ-123`
Repository change messages	Contains `PROJ-123`

Examples

Source Branch

CODE

feature/PROJ-123-login-validation

Pipeline Name

CODE

PROJ-123 Build Pipeline

Stage Name

CODE

Deploy PROJ-123

Deployments

Deployment information can be generated from both classic release pipelines and YAML-based deployment pipelines.

Issue keys can be detected from:

Location	Example
Commit messages included in the deployment range	Commit references `PROJ-123`
Release description	Contains `PROJ-123`
Deployment description	Contains `PROJ-123`
Deployment comment	Contains `PROJ-123`
Source branch	`feature/PROJ-123-login-validation`
CI trigger message	Contains `PROJ-123`
Source version information	References `PROJ-123`
Stage name	`Deploy PROJ-123`
Pipeline name	`PROJ-123 Production Deployment`
Deployment event message	Contains `PROJ-123`
Deployment event detailed message	Contains `PROJ-123`
Repository change messages	Contains `PROJ-123`

Examples

Release Description

CODE

Release for PROJ-123

Deployment Comment

CODE

Deploying fix for PROJ-123

Pipeline Name

CODE

PROJ-123 Production Deployment

Recommended Best Practices

For the most reliable issue association, we recommend including Jira issue keys in one or more of the following locations:

Branch names
Commit messages
Pull request titles
Pull request descriptions

Example Workflow

Branch

CODE

feature/PROJ-123-user-authentication

Commit

CODE

PROJ-123 Implement login endpoint

Pull Request Title

CODE

PROJ-123 Add user authentication

Following these conventions ensures that issue keys can be detected consistently throughout the development lifecycle and increases the likelihood that commits, branches, pull requests, builds, and deployments will be correctly linked to the corresponding Jira issue.

Updated: 01 Jun 2026