Jira Integration Skill

This skill enables direct interaction with Jira Cloud via REST API v3 and JQL queries.

Prerequisites

Set these environment variables (or in .env file):

JIRA_DOMAIN=company.atlassian.net JIRA_EMAIL=user@company.com JIRA_API_TOKEN=your-api-token

Generate API tokens at: https://id.atlassian.com/manage-profile/security/api-tokens

Core Workflows

1. Get Issue Details

To retrieve issue information:

python scripts/jira_api.py GET /issue/PROJ-123

With specific fields:

python scripts/jira_api.py GET "/issue/PROJ-123?fields=summary,status,assignee"

2. Search with JQL

To search issues using JQL:

python scripts/jira_api.py GET /search --query "jql=project=AOP AND status='In Progress'&maxResults=20"

Common JQL patterns - see references/jql-reference.md :

• My open issues: assignee = currentUser() AND resolution = Unresolved

• Recent updates: updated >= -1d ORDER BY updated DESC

• Sprint work: sprint in openSprints() AND assignee = currentUser()

3. Create Issue

To create a new issue, use ADF format for description (see references/adf-format.md ):

python scripts/jira_api.py POST /issue --data '{ "fields": { "project": { "key": "PROJ" }, "issuetype": { "name": "Task" }, "summary": "Issue title", "description": { "type": "doc", "version": 1, "content": [ { "type": "paragraph", "content": [{ "type": "text", "text": "Description here" }] } ] } } }'

4. Update Issue

To update fields on an existing issue:

python scripts/jira_api.py PUT /issue/PROJ-123 --data '{ "fields": { "summary": "Updated title", "labels": ["label1", "label2"] } }'

5. Add Comment

To add a comment (requires ADF format):

python scripts/jira_api.py POST /issue/PROJ-123/comment --data '{ "body": { "type": "doc", "version": 1, "content": [ { "type": "paragraph", "content": [{ "type": "text", "text": "Comment text here" }] } ] } }'

6. Transition Issue Status

First, get available transitions:

python scripts/jira_api.py GET /issue/PROJ-123/transitions

Then transition to new status:

python scripts/jira_api.py POST /issue/PROJ-123/transitions --data '{ "transition": { "id": "21" } }'

7. Assign Issue

To assign an issue:

Get user account ID first

python scripts/jira_api.py GET "/user/search?query=username"

Then assign

python scripts/jira_api.py PUT /issue/PROJ-123/assignee --data '{ "accountId": "user-account-id" }'

To unassign:

python scripts/jira_api.py PUT /issue/PROJ-123/assignee --data '{"accountId": null}'

Direct curl Usage

For quick operations without the helper script:

JIRA_DOMAIN="company.atlassian.net" AUTH=$(echo -n "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64)

curl -s "https://$JIRA_DOMAIN/rest/api/3/issue/PROJ-123"
-H "Authorization: Basic $AUTH"
-H "Content-Type: application/json"

Reference Files

• references/api-endpoints.md

• Complete REST API v3 endpoint reference

• references/jql-reference.md

• JQL operators, functions, fields, and patterns

• references/adf-format.md

• Atlassian Document Format for rich text fields

Common Patterns

Bulk Operations

To get multiple issues efficiently:

python scripts/jira_api.py GET /search --query "jql=key in (PROJ-1,PROJ-2,PROJ-3)"

Get Project Info

To list projects or get project details:

python scripts/jira_api.py GET /project python scripts/jira_api.py GET /project/PROJ

Get Available Issue Types

python scripts/jira_api.py GET "/project/PROJ?expand=issueTypes"

Error Handling

Common error codes:

• 400: Bad request - check JSON syntax and field names

• 401: Unauthorized - verify credentials

• 403: Forbidden - check user permissions

• 404: Not found - verify issue key exists

• 429: Rate limited - wait and retry

For field validation errors, Jira returns detailed error messages indicating which fields are invalid.