Jira PAT Skill

Manage Jira issues on self-hosted/enterprise Jira instances using Personal Access Tokens (PAT). This skill is designed for environments where Basic Auth doesn't work due to SSO/SAML authentication.

When to Use This Skill

Use this skill when working with:

• Self-hosted Jira instances (e.g., Red Hat, enterprise deployments)
• Jira instances with SSO/SAML authentication
• Environments where jira-cli or Basic Auth fails

Note: For Atlassian Cloud with email + API token auth, use the clawdbot-jira-skill instead.

Prerequisites

1. Personal Access Token (PAT): Create one in Jira:

   • Go to your Jira profile → Personal Access Tokens
   • Create a new token with appropriate permissions
   • Store it in environment variable JIRA_PAT

2. Jira Base URL: Your Jira instance URL in JIRA_URL

Environment Variables

export JIRA_PAT="your-personal-access-token"
export JIRA_URL="https://issues.example.com"

Tools

This skill uses curl and jq for all operations.

Instructions

Get Issue Details

Fetch full details of a Jira issue:

curl -s -H "Authorization: Bearer $JIRA_PAT" \
  "$JIRA_URL/rest/api/2/issue/PROJECT-123" | jq

Get specific fields only:

curl -s -H "Authorization: Bearer $JIRA_PAT" \
  "$JIRA_URL/rest/api/2/issue/PROJECT-123?fields=summary,status,description" | jq

Search Issues (JQL)

# Find child issues of an epic
curl -s -H "Authorization: Bearer $JIRA_PAT" \
  "$JIRA_URL/rest/api/2/search?jql=parent=EPIC-123" | jq

# Complex queries (URL-encoded)
curl -s -H "Authorization: Bearer $JIRA_PAT" \
  "$JIRA_URL/rest/api/2/search?jql=project%3DPROJ%20AND%20status%3DOpen" | jq

Common JQL patterns:

• parent=EPIC-123 - Child issues of an epic
• project=PROJ AND status=Open - Open issues in project
• assignee=currentUser() - Your assigned issues
• labels=security - Issues with specific label
• updated >= -7d - Recently updated

Get Available Transitions

Before changing status, query available transitions:

curl -s -H "Authorization: Bearer $JIRA_PAT" \
  "$JIRA_URL/rest/api/2/issue/PROJECT-123/transitions" | jq '.transitions[] | {id, name}'

Transition (Change Status)

Close an issue with a comment:

curl -s -X POST \
  -H "Authorization: Bearer $JIRA_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "transition": {"id": "61"},
    "update": {
      "comment": [{"add": {"body": "Closed via API"}}]
    }
  }' \
  "$JIRA_URL/rest/api/2/issue/PROJECT-123/transitions"

Add a Comment

curl -s -X POST \
  -H "Authorization: Bearer $JIRA_PAT" \
  -H "Content-Type: application/json" \
  -d '{"body": "Comment added via API."}' \
  "$JIRA_URL/rest/api/2/issue/PROJECT-123/comment"

Update Issue Fields

curl -s -X PUT \
  -H "Authorization: Bearer $JIRA_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "summary": "Updated summary",
      "labels": ["api", "automated"]
    }
  }' \
  "$JIRA_URL/rest/api/2/issue/PROJECT-123"

Create an Issue

curl -s -X POST \
  -H "Authorization: Bearer $JIRA_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "project": {"key": "PROJ"},
      "summary": "New issue via API",
      "description": "Issue description",
      "issuetype": {"name": "Task"},
      "parent": {"key": "EPIC-123"}
    }
  }' \
  "$JIRA_URL/rest/api/2/issue"

Useful jq Filters

# Summary and status
jq '{key: .key, summary: .fields.summary, status: .fields.status.name}'

# List search results
jq '.issues[] | {key: .key, summary: .fields.summary, status: .fields.status.name}'

# Issue links
jq '.fields.issuelinks[] | {type: .type.name, key: (.inwardIssue // .outwardIssue).key}'

Troubleshooting

Error	Cause	Solution
401 Unauthorized	Invalid/expired PAT	Regenerate token, check Bearer format
404 Not Found	Issue doesn't exist or no access	Verify issue key and permissions
400 Bad Request on transition	Invalid transition ID	Query available transitions first

Comparison with Basic Auth Skills

This skill uses Bearer token authentication (Authorization: Bearer <PAT>), which works with self-hosted Jira instances using SSO/SAML. For Atlassian Cloud with email + API token, use skills that implement Basic Auth instead.