jira

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name JIRA_API_TOKEN` or `zero doctor check-connector --url https://your-domain.atlassian.net/rest/api/3/myself --method GET`

## How to Use

All examples below assume `JIRA_DOMAIN`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` are set.

Base URL: `https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3`

> Note: `${JIRA_DOMAIN%.atlassian.net}` strips the suffix if present, so both `mycompany` and `mycompany.atlassian.net` work.

### 1. Get Current User

Verify your authentication:

```bash
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/myself" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json"
```

### 2. List Projects

Get all projects you have access to:

```bash
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/project" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json"
```

### 3. Get Project Details

Get details for a specific project:

```bash
PROJECT_KEY="PROJ"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/project/${PROJECT_KEY}" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json"
```

### 4. Get Issue Types for Project

List available issue types (Task, Bug, Story, etc.):

```bash
PROJECT_KEY="PROJ"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/project/${PROJECT_KEY}" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json"
```

### 5. Search Issues with JQL

Search issues using Jira Query Language:

Write to `/tmp/jira_request.json`:

```json
{
  "jql": "project = PROJ AND status NOT IN (Done) ORDER BY created DESC",
  "maxResults": 10,
  "fields": ["key", "summary", "status", "assignee", "priority"]
}
```

Then run:

```bash
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/search/jql" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json | jq '.issues[] | {key, summary: .fields.summary, status: .fields.status.name, assignee: .fields.assignee.displayName, priority: .fields.priority.name}'
```

Common JQL examples:
- `project = PROJ` - Issues in project
- `assignee = currentUser()` - Your issues
- `status = "In Progress"` - By status
- `status NOT IN (Done, Closed)` - Exclude statuses
- `created >= -7d` - Created in last 7 days
- `labels = bug` - By label
- `priority = High` - By priority

### 6. Get Issue Details

Get full details of an issue:

```bash
ISSUE_KEY="PROJ-123"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/issue/${ISSUE_KEY}" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json"
```

### 7. Create Issue

Create a new issue (API v3 uses Atlassian Document Format for description):

Write to `/tmp/jira_request.json`:

```json
{
  "fields": {
    "project": {"key": "PROJ"},
    "summary": "Bug: Login button not responding",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "The login button on the mobile app is not responding when tapped."}
          ]
        }
      ]
    },
    "issuetype": {"name": "Bug"}
  }
}
```

Then run:

```bash
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/issue" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json
```

### 8. Create Issue with Priority and Labels

Create issue with additional fields:

Write to `/tmp/jira_request.json`:

```json
{
  "fields": {
    "project": {"key": "PROJ"},
    "summary": "Implement user authentication",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "Add OAuth2 authentication flow for the mobile app."}
          ]
        }
      ]
    },
    "issuetype": {"name": "Story"},
    "priority": {"name": "High"},
    "labels": ["backend", "security"]
  }
}
```

Then run:

```bash
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/issue" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json
```

### 9. Update Issue

Update an existing issue:

```bash
ISSUE_KEY="PROJ-123"
```

Write to `/tmp/jira_request.json`:

```json
{
  "fields": {
    "summary": "Updated: Login button not responding on iOS",
    "priority": {"name": "Highest"},
    "labels": ["bug", "ios", "urgent"]
  }
}
```

Then run:

```bash
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X PUT "${JIRA_BASE}/issue/${ISSUE_KEY}" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json
```

Returns 204 No Content on success.

### 10. Get Available Transitions

Get possible status transitions for an issue:

```bash
ISSUE_KEY="PROJ-123"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/issue/${ISSUE_KEY}/transitions" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json"
```

### 11. Transition Issue (Change Status)

Move issue to a different status:

```bash
ISSUE_KEY="PROJ-123"
TRANSITION_ID="31" # Get from transitions endpoint
```

Write to `/tmp/jira_request.json`:

```json
{
  "transition": {
    "id": "<your-transition-id>"
  }
}
```

Then run:

```bash
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/issue/${ISSUE_KEY}/transitions" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json
```

Returns 204 No Content on success.

### 12. Add Comment

Add a comment to an issue:

```bash
ISSUE_KEY="PROJ-123"
```

Write to `/tmp/jira_request.json`:

```json
{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          {"type": "text", "text": "Investigated and found the root cause. Working on a fix."}
        ]
      }
    ]
  }
}
```

Then run:

```bash
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/issue/${ISSUE_KEY}/comment" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json
```

### 13. Get Issue Comments

List all comments on an issue:

```bash
ISSUE_KEY="PROJ-123"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/issue/${ISSUE_KEY}/comment" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json"
```

### 14. Assign Issue

Assign an issue to a user:

```bash
ISSUE_KEY="PROJ-123"
ACCOUNT_ID="5b10ac8d82e05b22cc7d4ef5" # Get from /rest/api/3/user/search
```

Write to `/tmp/jira_request.json`:

```json
{
  "accountId": "<your-account-id>"
}
```

Then run:

```bash
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X PUT "${JIRA_BASE}/issue/${ISSUE_KEY}/assignee" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json
```

### 15. Search Users

Find users by email or name:

Write to `/tmp/jira_search.txt`:

```
john
```

```bash
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -G "${JIRA_BASE}/user/search" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept