Jira Cloud Integration

Jira Cloud REST API integration for issue tracking, sprint management, and worklog operations.

Authentication

Jira Cloud uses API token authentication. Required environment variables:

• JIRA_BASE_URL - Your Jira instance (e.g., https://yourcompany.atlassian.net)
• JIRA_USER_EMAIL - Atlassian account email
• JIRA_API_TOKEN - API token from https://id.atlassian.com/manage-profile/security/api-tokens

Test connection:

curl -s -u "$JIRA_USER_EMAIL:$JIRA_API_TOKEN" "$JIRA_BASE_URL/rest/api/3/myself" | jq .

Quick Reference

All operations use the scripts/jira.py script:

Common Workflows

Search Issues

JQL (Jira Query Language) supports powerful filtering:

# Open issues assigned to me
jira.py search "assignee = currentUser() AND status != Done"

# Issues updated this week
jira.py search "project = PROJ AND updated >= startOfWeek()"

# High priority bugs
jira.py search "type = Bug AND priority in (High, Highest)"

# Issues in current sprint
jira.py search "sprint in openSprints() AND project = PROJ"

Output: JSON array of issues with key, summary, status, assignee, priority.

Create Issues

# Basic task
jira.py create PROJ --type Task --summary "Implement feature X"

# Bug with description and priority
jira.py create PROJ --type Bug \
  --summary "Login fails on mobile" \
  --description "Steps to reproduce: 1. Open app 2. Enter credentials" \
  --priority High

# Story with labels and components
jira.py create PROJ --type Story \
  --summary "User profile page" \
  --labels "frontend,ui" \
  --components "Web App"

Update Issues

# Update summary
jira.py update PROJ-123 --summary "Updated title"

# Update multiple fields
jira.py update PROJ-123 \
  --description "New description" \
  --priority Medium \
  --labels "backend,api"

# Assign to user
jira.py update PROJ-123 --assignee "user@company.com"

Status Transitions

Transitions depend on workflow configuration. Get available transitions first:

# List available transitions
jira.py transitions PROJ-123

# Move to status
jira.py transition PROJ-123 "In Progress"
jira.py transition PROJ-123 "Done"

Sprint Management

# List all boards
jira.py boards

# Get sprints for a board
jira.py sprints 42

# Get active sprint issues
jira.py sprint-issues 100

# Filter: only active sprints
jira.py sprints 42 --state active

Work Logging

# Log time spent
jira.py worklog PROJ-123 --time "1h 30m" --comment "Code review"

# Log with specific date
jira.py worklog PROJ-123 --time "4h" --started "2024-03-14T09:00:00.000+0000"

# View existing worklogs
jira.py worklogs PROJ-123

Field Reference

See references/fields.md for:

• Standard field names and IDs
• Custom field handling
• ADF (Atlassian Document Format) for rich text

Error Handling

Common errors:

• 401 Unauthorized: Check JIRA_USER_EMAIL and JIRA_API_TOKEN
• 404 Not Found: Issue key or project doesn't exist
• 400 Bad Request: Invalid field values or missing required fields

Raw API Access

For operations not covered by the script:

# GET request
curl -s -u "$JIRA_USER_EMAIL:$JIRA_API_TOKEN" \
  "$JIRA_BASE_URL/rest/api/3/issue/PROJ-123" | jq .

# POST request
curl -s -X POST -u "$JIRA_USER_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Comment"}]}]}}' \
  "$JIRA_BASE_URL/rest/api/3/issue/PROJ-123/comment" | jq .

API docs: https://developer.atlassian.com/cloud/jira/platform/rest/v3/