---
name: jira
description: |
  Jira REST API access for Investibook agents. Use when reading Jira issues,
  fetching comments, extracting O11Y alert metadata, and searching issues by
  cluster_id / tenant_id / alert name. Read-only — no write operations.
---

# Jira

Use this skill for Jira issue context during Investibook investigations. Prefer
the bundled script so requests are authenticated and JSON-shaped consistently.

## Authentication

The script reads credentials from the workspace process environment:

- Base URL: `INVESTIBOOK_JIRA_BASE_URL`, then `JIRA_BASE_URL`, default `https://tidb.atlassian.net`
- Username: `INVESTIBOOK_JIRA_USERNAME`, then `JIRA_USERNAME`
- API token: `INVESTIBOOK_JIRA_API_TOKEN`, then `JIRA_PASSWORD`

Do not print or log token values.

## Commands

Run from the workspace root:

```bash
python3 .opencode/skills/builtin/jira/scripts/jira_api.py get-issue --issue-key O11Y-1956041
python3 .opencode/skills/builtin/jira/scripts/jira_api.py get-alert-info --issue-key O11Y-1956041
python3 .opencode/skills/builtin/jira/scripts/jira_api.py get-comments --issue-key O11Y-1956041
python3 .opencode/skills/builtin/jira/scripts/jira_api.py search-by-cluster --cluster-id 1234567890
python3 .opencode/skills/builtin/jira/scripts/jira_api.py search-by-tenant --tenant-id tenant_abc123
python3 .opencode/skills/builtin/jira/scripts/jira_api.py search-by-alert-name --alert-name HighCPUUsage
```

| Command | Required args | Optional args | Description |
|---|---|---|---|
| `get-issue` | `--issue-key` | | Fetch full issue JSON |
| `get-alert-info` | `--issue-key` | | Extract O11Y alert metadata (tenant, cluster, alert name, org) |
| `get-comments` | `--issue-key` | | Fetch all comments on an issue |
| `search-by-cluster` | `--cluster-id` | `--project` (default O11Y), `--max-results` (default 50), `--next-page-token` | Search issues by Cluster ID (`customfield_10149`) |
| `search-by-tenant` | `--tenant-id` | `--project` (default O11Y), `--max-results` (default 50), `--next-page-token` | Search issues by Tenant ID (`customfield_10157`) |
| `search-by-alert-name` | `--alert-name` | `--project` (default O11Y), `--max-results` (default 50), `--next-page-token` | Search issues by alert name (summary text match) |

## Search Commands

All search commands build JQL internally — just pass the identifier.
Jira's current `/rest/api/3/search/jql` endpoint uses cursor pagination. If a
response includes `nextPageToken` and `isLast` is false, pass that value with
`--next-page-token` to fetch the next page.

### search-by-cluster

Use when looking up all alerts/incidents for a specific cluster.

```bash
python3 .opencode/skills/builtin/jira/scripts/jira_api.py search-by-cluster \
  --cluster-id 1234567890

python3 .opencode/skills/builtin/jira/scripts/jira_api.py search-by-cluster \
  --cluster-id 1234567890 --project TCOC
```

### search-by-tenant

Use when looking up all alerts/incidents for a specific tenant.

```bash
python3 .opencode/skills/builtin/jira/scripts/jira_api.py search-by-tenant \
  --tenant-id tenant_abc123

python3 .opencode/skills/builtin/jira/scripts/jira_api.py search-by-tenant \
  --tenant-id tenant_abc123 --project TCOC
```

### search-by-alert-name

Use when looking up issues with a specific alert name (matches in summary).

```bash
python3 .opencode/skills/builtin/jira/scripts/jira_api.py search-by-alert-name \
  --alert-name HighCPUUsage

python3 .opencode/skills/builtin/jira/scripts/jira_api.py search-by-alert-name \
  --alert-name HighCPUUsage --project TCOC --max-results 20
```

## Write Policy

This skill is **read-only**. No Jira write operations (comments, transitions,
updates) are available. All analysis should be presented to the user directly.