Jira Integration

Jira Integration

How to talk to Jira from a coding session: authenticate, read an issue, act on it, and record progress against it. The content rules for a work item, what it should say and when it may close, live in project-tracking, and this skill defers to them rather than restating them.

When to activate

• Fetching a Jira issue to understand what is being asked
• Searching for issues with a JQL query
• Adding a progress comment to an issue during or after implementation
• Transitioning an issue through the project workflow
• Linking a branch, pull request or merge request back to an issue key
• Diagnosing a failing Jira call, such as a 401 or a rejected transition

When not to activate

• Deciding what an item should contain, how it is sized, or when it may close, use project-tracking
• Operating GitHub issues, pull requests and releases, use github-ops
• Naming the branch or writing the commit message that carries the key, use git-workflow
• Writing the tests the acceptance criteria imply, use tdd-workflow or the language test skill
• Reviewing the code the ticket produced, use code-reviewer

Configure the server in your tool's own MCP file

This repository keeps one MCP configuration file per agent tool, and a server has to be declared in the file the tool actually reads. Add the Atlassian MCP server there, following the setup document docs/MCP_SETUP.md, which lists the file each tool reads and the schema each one expects.

Two rules hold regardless of tool. The secret comes from the process environment, never as a literal value inside a configuration file that can be committed. Do not pin the server package to a version in project configuration, so a consumer picks up fixes without editing a file this repository owns.

Pass:

JIRA_URL, JIRA_EMAIL and JIRA_API_TOKEN exported in the shell that starts the agent. Config file names the server only.

Fail:

{"env": {"JIRA_API_TOKEN": "the-real-token-pasted-into-a-committed-file"}}

Create the token at the Atlassian account security page, store it in the environment or a secrets manager, and scope it to the projects you actually need. Rotate it immediately if it ever reaches git history.

Fall back to REST v3 when no MCP server is available

The REST API answers the same questions over curl. It needs the same three environment variables.

Validate that all three are set before the first call and fail with a clear message if not, because an unset variable produces a 401 that reads like a permissions problem.

Know which MCP tool answers which question

Read a transition ID before transitioning

Transition IDs are per project workflow and change between projects, so an ID that worked on one board fails on the next. Ask for the available transitions first, match on the name, then execute.

Read the available transitions:

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name}'

Then execute the one you matched:

curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" -H "Content-Type: application/json" -d '{"transition": {"id": "31"}}' "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"

Pass:

Fetched transitions, "In Review" is id 31 on this board, transitioned with 31.

Fail:

Used transition id 21 because that was "In Review" on the last project.

Fetch an issue with the fields you need

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{key, summary: .fields.summary, status: .fields.status.name, type: .fields.issuetype.name, labels: .fields.labels, description: .fields.description}'

Fetch the comment thread separately, because it is large and usually not needed:

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | {author: .author.displayName, created: .created[:10], body: .body}'

Search with JQL:

curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --data-urlencode "jql=project = PROJ AND status = 'In Progress'" "$JIRA_URL/rest/api/3/search"

Post a comment in Atlassian document format

The v3 comment endpoint takes a structured document, not a plain string. A plain string is rejected with a 400 that does not say why.

curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" -H "Content-Type: application/json" -d '{"body":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Branch feat/PROJ-1234 pushed."}]}]}}' "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment"

Pass:

Comment body wrapped in the doc structure with a paragraph node.

Fail:

{"body": "Branch pushed."}

Write only the fields the user named

Create or modify an issue only when the user asked for it, and set only the fields they named. Adding a label, a component, a priority or a sprint on your own edits somebody else's board, and the change is invisible until a filter returns the wrong set. Take the description template from the tracker rather than inventing one.

Pass:

Asked for a bug in PROJ with that summary and description. Created exactly those two fields. Nothing else set.

Fail:

Created it and added the "backend" component, priority High and the current sprint, since that seemed right.

Update as you go, at the points that carry information

Keep each comment short and link outward rather than pasting content. A comment that reproduces a test report goes stale the moment the report is regenerated, and a link never does.

Pass:

PR opened: <link>. 6 tests added covering the 429 path. Ready for review.

Fail:

[400 lines of pasted test output]

Defer the content of the item to project-tracking

What a good acceptance criterion looks like, how to size and split an item, which label taxonomy is allowed, and what has to be true before an item closes are all owned by project-tracking. Read that skill before you write a description, criteria or a closure comment, and use this skill only for getting that content into and out of Jira.

Where criteria are vague, ask before writing code rather than inventing an interpretation, and check linked issues first so you understand the full scope of the feature.

Troubleshooting

Related skills

• project-tracking owns item kinds, sizing, acceptance criteria, labels, statuses and closure rules
• github-ops owns the same operational surface when the tracker is GitHub issues
• git-workflow owns branch naming and commit messages that carry the issue key
• code-reviewer owns reviewing the change the issue produced
• security-review owns handling and rotation of the API token itself

Checklist

• Credentials come from the process environment, never a literal in a config file
• The MCP server is declared in the file the running tool actually reads
• No version pin was added to project MCP configuration
• Transitions were read for this issue before one was executed
• Only the fields the user named were written
• Comments link outward rather than pasting reports
• Item content follows project-tracking, not conventions invented here