#Jira Integration

DevBoy tools provides integration with Jira for managing issues through AI assistants. Both Jira Cloud and Jira Self-Hosted (Data Center) are supported. The deployment flavor is auto-detected from the URL.

#Authentication

Jira supports different authentication methods depending on the deployment type:

:::tip[Auto-detection] The deployment flavor is automatically detected from the URL:

• URLs containing .atlassian.net are treated as Jira Cloud (API v3)
• All other URLs are treated as Self-Hosted (API v2) :::

#Configuration

#Basic configuration

# Set Jira instance URL
devboy config set jira.url https://company.atlassian.net

# Set project key
devboy config set jira.project_key PROJ

# Set email (used for Cloud authentication)
devboy config set jira.email user@example.com

# Store token in OS keychain
devboy config set-secret jira.token <token>

#Configuration file

Settings are stored in ~/.config/devboy-tools/config.toml:

[jira]
url = "https://company.atlassian.net"
project_key = "PROJ"
email = "user@example.com"

The token is stored separately in the OS keychain for security.

#Self-hosted Jira

For Jira Server or Data Center instances:

devboy config set jira.url https://jira.company.com
devboy config set jira.project_key PROJ
devboy config set jira.email user@company.com

# Using a Personal Access Token (PAT):
devboy config set-secret jira.token <pat-token>

# Or using basic auth (user:password):
devboy config set-secret jira.token "username:password"

:::note For Self-Hosted Jira, the email field is still required in the config but is only used for Cloud authentication. With Self-Hosted, authentication is determined by the token format:

• Token without : is treated as a Bearer PAT
• Token with : is treated as Basic Auth credentials :::

#MCP tools

Once configured, the following MCP tools are available:

#Issue tools

#Project version tools

Manage Jira project versions (a.k.a. fixVersion targets / releases). Two-tool surface — there is no per-id get_version; list_project_versions returns enough fields per item that an extra round-trip is unnecessary (see docs/research/paper-3-context-enrichment.md).

Both endpoints work on Jira Cloud and Self-Hosted/DC. Server/DC ignores Cloud-only ?expand=issuesstatus, so issue_count from list_project_versions is populated only on Cloud — Self-Hosted callers fall back to issuesUnresolvedCount from the base payload.

For per-issue details on a release, follow up with get_issues and a JQL nativeQuery like fixVersion = "3.18.0".

When list_project_versions had to truncate to fit limit, the response footer carries a [+N more — call with limit: …] hint so you can ask for the rest.

#Issue key format

Jira issues use the standard Jira key format: PROJ-123 (project key + number).

#State filtering

The state filter maps to Jira status categories:

#Sorting

Use sort_by and sort_order parameters to control issue ordering:

#Status Changes

Status changes are performed via Jira transitions. When updating an issue's state, the tool:

1. Fetches available transitions for the issue
2. Finds a transition whose target status matches (case-insensitive)
3. Executes the transition

If no matching transition is found, the tool returns an error with available statuses.

#Priority mapping

Jira priorities are mapped to the unified format:

#Atlassian Document Format (ADF)

Jira Cloud uses ADF for rich text content. The integration handles this automatically:

• Creating/updating: Plain text is converted to ADF paragraphs
• Reading: ADF documents are converted back to plain text

Jira Self-Hosted uses plain text directly.

#Merge request tools

Jira does not have merge requests. All MR-related tools will return a ProviderUnsupported error when used with Jira. Use a GitHub or GitLab provider for MR operations.

#Output formats

All tools support three output formats via the format parameter:

• markdown (default) - Human-readable with formatting
• compact - Condensed format for limited context
• json - Raw JSON data

Example:

{
  "key": "jira#PROJ-123",
  "format": "json"
}

#Testing

Verify your Jira configuration:

devboy test jira

This will test the connection by calling the /myself endpoint and display your Jira user information.

#Troubleshooting

#"401 Unauthorized" error

• Cloud: Verify your API token and email are correct. API tokens are generated at Atlassian API Tokens
• Self-Hosted (PAT): Check that the Personal Access Token hasn't expired
• Self-Hosted (basic): Verify username and password are correct

#"404 Not Found" error

• Verify the project key is correct (e.g., PROJ, not the full project name)
• Ensure the issue exists when using get_issue
• Check that your Jira URL doesn't have a trailing path (use https://jira.company.com, not https://jira.company.com/jira)

#"403 Forbidden" error

• Your token may lack permissions for the project
• Check project-level permissions in Jira administration
• For Cloud, ensure the API token is for the correct Atlassian account

#"No transition found" error

• The target status may not be reachable from the current status
• Check the issue's current workflow in Jira
• Use the exact status name as shown in Jira (case-insensitive)

#Rate limiting

Jira API has rate limits:

• Jira Cloud: Rate limits vary, typically generous for API tokens
• Self-Hosted: Depends on instance configuration
• The tool will show a rate limit error if exceeded