Jira

Prerequisites

The script at .github/skills/jira/jira requires python3 (3.6+).

Environment variables (must be set before running any command):

| Variable | When required | Purpose | |----------|--------------|---------| | JIRA_BASE_URL | Always | Jira instance URL (e.g., https://company.atlassian.net) | | JIRA_USER_EMAIL | Cloud | Account email for basic auth | | JIRA_API_TOKEN | Cloud | API token paired with email | | JIRA_PAT | Server/DC | Personal access token (bearer auth) |

Auth is auto-detected: if JIRA_PAT is set → Server/DC bearer auth. Otherwise → Cloud basic auth with email + token.

If a command fails with JIRA_BASE_URL is not set, verify the env vars are exported in the current shell.

Output Modes

All read commands (search, get, comments) support a --fields flag that extracts specific fields using dot-notation, outputting tab-separated values instead of raw JSON. Always use --fields by default to keep output concise:

.github/skills/jira/jira search 'assignee = currentUser()' --fields key,fields.summary,fields.status.name
.github/skills/jira/jira get PROJ-123 --fields key,fields.summary,fields.status.name,fields.assignee.displayName
.github/skills/jira/jira comments PROJ-123 PROJ-456 --fields _issue,author.displayName,created,body

For lists, output includes a header row. For single items, output is field: value per line. Nested fields use dot-notation (e.g. fields.status.name). Omit --fields only when the full JSON is needed.

Command Reference

All commands use the full path: .github/skills/jira/jira [args...]

| Command | Purpose | Syntax | |---------|---------|--------| | search | Find issues via JQL | .github/skills/jira/jira search '' [max_results] | | get | Fetch a single issue | .github/skills/jira/jira get | | create | Create a new issue | .github/skills/jira/jira create '' | | update | Update issue fields | .github/skills/jira/jira update '' | | transition | Change issue status | .github/skills/jira/jira transition '' | | comment | Add a comment | .github/skills/jira/jira comment '' | | comments | List comments on issues | .github/skills/jira/jira comments [ISSUE-KEY ...] | | fields | Discover issue types & fields | .github/skills/jira/jira fields [issue-type-id] |

Workflows

Look Up an Issue

.github/skills/jira/jira get PROJ-123

Output: full issue JSON including key, summary, description, status, assignee, priority, labels, and comments.

Search for Issues

.github/skills/jira/jira search 'project = PROJ AND status = "In Progress"'
.github/skills/jira/jira search 'assignee = currentUser() ORDER BY updated DESC' 10

Important (Cloud): The new search API requires a bounded query. Always include a project, assignee, or other filter — bare ORDER BY queries will fail.

Create an Issue (Step-by-Step)

Step 1 — Discover issue types:

.github/skills/jira/jira fields PROJ

Output includes issue type IDs. Find the one you need (e.g., Task → 10045).

Step 2 — Discover required fields for that issue type:

.github/skills/jira/jira fields PROJ 10045

Look at "required": true fields in the response. Every project may have custom required fields beyond the standard ones.

Step 3 — Build the JSON payload and create:

.github/skills/jira/jira create '{
  "fields": {
    "project": { "key": "PROJ" },
    "summary": "Short description of the issue",
    "issuetype": { "name": "Task" }
  }
}'

Output: { "id": "...", "key": "PROJ-42", "self": "..." }

Update an Issue

Only include fields you want to change:

.github/skills/jira/jira update PROJ-123 '{
  "fields": {
    "summary": "Updated summary",
    "priority": { "name": "High" },
    "labels": ["backend", "urgent"]
  }
}'

Note: You cannot change status via update — use transition instead.

Transition an Issue (Change Status)

Use a transition name (e.g., "In Progress", "Done") or a transition ID:

.github/skills/jira/jira transition PROJ-123 "In Progress"
.github/skills/jira/jira transition PROJ-123 "Done"

If the transition name is not found, the script lists available transitions in the error output.

Add a Comment

.github/skills/jira/jira comment PROJ-123 "PR #42 addresses this issue."

Or pipe from stdin:

echo "Deployed to staging." | .github/skills/jira/jira comment PROJ-123

JSON Field Reference

Common Field Patterns

| Field | JSON format | |-------|-------------| | project | { "key": "PROJ" } | | issuetype | { "name": "Task" } or { "name": "Bug" } | | summary | "Short description" | | description | "Detailed description" | | priority | { "name": "High" } — values: Highest, High, Medium, Low, Lowest | | assignee | { "accountId": "5e..." } (Cloud) or { "name": "jsmith" } (Server) | | labels | ["backend", "security"] | | components | [{ "name": "API" }] | | Custom fields | "customfield_10001": "value" — use fields command to discover |

Full Create Example

{
  "fields": {
    "project": { "key": "PROJ" },
    "summary": "Fix login timeout on mobile",
    "issuetype": { "name": "Bug" },
    "description": "Users on iOS report 30s timeout during OAuth flow.",
    "priority": { "name": "High" },
    "labels": ["mobile", "auth"],
    "components": [{ "name": "Authentication" }]
  }
}

Common JQL Patterns

| Goal | JQL | |------|-----| | My open issues | assignee = currentUser() AND resolution = Unresolved | | Sprint backlog | project = PROJ AND sprint in openSprints() | | Recently updated | project = PROJ AND updated >= -7d ORDER BY updated DESC | | Bugs by priority | project = PROJ AND issuetype = Bug ORDER BY priority ASC | | Unassigned issues | project = PROJ AND assignee is EMPTY | | Text search | project = PROJ AND text ~ "login error" |

Troubleshooting

| Error | Cause | Fix | |-------|-------|-----| | JIRA_BASE_URL is not set | Env vars not exported | Export all required env vars in current shell | | HTTP 401 | Bad credentials | Verify API token/PAT is correct and not expired | | HTTP 403 | Insufficient permissions | Check the token's project/scope permissions | | HTTP 404 | Wrong issue key or URL | Verify JIRA_BASE_URL and issue key exist | | HTTP 410 | Deprecated endpoint | You're hitting a removed Cloud API — update the script | | transition '...' not found | Invalid transition name | Check available transitions with get (look at status) | | invalid issue key | Key doesn't match PROJ-123 format | Use uppercase project key + number | | python3 is required | python3 not in PATH | Install python3 for your platform |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: peteroden
• Source: peteroden/jira-and-gitlab-skills
• License: MIT

Install and usage instructions live in the source repository linked above.