jira

What this skill does

# Jira

Interact with Jira for issue tracking, search, and workflow management.

## Installation

1. **Install Python dependencies**:
   ```bash
   pip install --user requests keyring pyyaml
   ```

2. **Download the skill** from [Releases](https://github.com/odyssey4me/agent-skills/releases) or use directly from this repository.

## Setup Verification

After installation, verify the skill is properly configured:

```bash
$SKILL_DIR/scripts/jira.py check
```

This will check:
- Python dependencies (requests, keyring, pyyaml)
- Authentication configuration
- Connectivity to Jira

If anything is missing, the check command will provide setup instructions.

## Authentication

Configure Jira authentication using one of these methods:

### Option 1: Environment Variables (Recommended)

```bash
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-token"
```

Add these to your `~/.bashrc` or `~/.zshrc` for persistence.

### Option 2: Config File

Create `~/.config/agent-skills/jira.yaml`:

```yaml
url: https://yourcompany.atlassian.net
email: [email protected]
token: your-token
```

### Required Credentials

- **URL**: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`)
- **Email**: Your Atlassian account email
- **API Token**: Create at https://id.atlassian.com/manage-profile/security/api-tokens

## Configuration Defaults

Optionally configure defaults in `~/.config/agent-skills/jira.yaml` to reduce repetitive typing:

```yaml
# Authentication (optional if using environment variables)
url: https://yourcompany.atlassian.net
email: [email protected]
token: your-token

# Optional defaults
defaults:
  jql_scope: "project = DEMO AND assignee = currentUser()"
  security_level: "Internal"
  max_results: 25
  fields: ["summary", "status", "assignee", "priority", "created"]
  custom_fields:
    story_points: "customfield_10028"
    assigned_team: "customfield_12345"
  custom_field_schemas:
    story_points: "number"
    assigned_team: "option"

# Optional project-specific defaults
projects:
  DEMO:
    issue_type: "Task"
    priority: "Medium"
  PROD:
    issue_type: "Bug"
    priority: "High"
```

### How Defaults Work

- **CLI arguments always override** config defaults
- **JQL scope** is prepended to all searches: `(scope) AND (your_query)`
- **Security level** applies to comments and transitions with comments
- **Project defaults** apply when creating issues in that project
- **Custom fields** map friendly names to instance-specific custom field IDs.
  These fields are automatically included in API requests and displayed in
  formatted output. If a mapping is not configured, the skill auto-discovers
  the field ID and schema type from the Jira API and saves both to the config.
  Use `--set-field NAME=VALUE` on `issue create` and `issue update` to set
  custom field values using the friendly name.
- **Custom field schemas** store the Jira schema type for each custom field
  (e.g. `number`, `option`, `securitylevel`). This lets `--set-field` wrap
  values correctly (e.g. `{"value": "..."}` for options) without extra API
  calls. Schemas are saved automatically during discovery. If missing, run
  `config discover <field_name>` to populate them.

### View Configuration

```bash
# Show all configuration
$SKILL_DIR/scripts/jira.py config show

# Show project-specific defaults
$SKILL_DIR/scripts/jira.py config show --project DEMO
```

## Commands

See [permissions.md](references/permissions.md) for read/write classification of each command.

### check

Verify configuration and connectivity.

```bash
$SKILL_DIR/scripts/jira.py check
```

This validates:
- Python dependencies are installed
- Authentication is configured
- Can connect to Jira
- API version is detected correctly

### search

Search for issues using JQL (Jira Query Language).

```bash
$SKILL_DIR/scripts/jira.py search "project = DEMO AND status = Open"
$SKILL_DIR/scripts/jira.py search "assignee = currentUser() ORDER BY updated DESC" --max-results 20
```

**Arguments:**
- `jql`: JQL query string (required unless `--contributor` is used)
- `--contributor`: Search for issues where this user is a contributor (reporter, assignee, or commenter). On Jira Cloud, automatically resolves email/name to accountId.
- `--project`: Project key to scope a `--contributor` search
- `--max-results`: Maximum number of results (default: 50)
- `--fields`: Comma-separated list of fields to include

**Deployment-specific queries:**

The available JQL functions depend on your Jira deployment type. Run
`check` to see your deployment type and ScriptRunner availability.

- **All deployments**: See [jql-reference.md](references/jql-reference.md)
  for standard JQL patterns (status, dates, fields, ordering).
- **Data Center/Server with ScriptRunner**: See
  [scriptrunner.md](references/scriptrunner.md) for advanced functions
  like `linkedIssuesOf()`, `subtasksOf()`, `commentedByUser()`.
- **Jira Cloud**: ScriptRunner functions are **not available**. Use the
  Cloud-native alternatives documented in
  [jql-reference.md](references/jql-reference.md#cloud-alternatives).

### issue

Get, create, update, or comment on issues.

```bash
# Get issue details
$SKILL_DIR/scripts/jira.py issue get DEMO-123

# Get issue with specific fields only
$SKILL_DIR/scripts/jira.py issue get DEMO-123 --fields "summary,status,assignee"

# Get issue with contributors listed
$SKILL_DIR/scripts/jira.py issue get DEMO-123 --contributors

# List comments on an issue
$SKILL_DIR/scripts/jira.py issue comments DEMO-123
$SKILL_DIR/scripts/jira.py issue comments DEMO-123 --max-results 10

# Create new issue
$SKILL_DIR/scripts/jira.py issue create --project DEMO --type Task --summary "New task"

# Create issue with custom fields
$SKILL_DIR/scripts/jira.py issue create --project DEMO --type Story --summary "New story" --set-field story_points=5

# Update issue
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --summary "Updated summary"

# Update custom fields
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --set-field assigned_team="Platform Team"

# Create issue from a markdown file
$SKILL_DIR/scripts/jira.py issue create --from-file issue.md

# Create issue from file with CLI overrides
$SKILL_DIR/scripts/jira.py issue create --from-file issue.md --priority Critical

# Update issue from a markdown file
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --from-file changes.md

# Create issue with links
$SKILL_DIR/scripts/jira.py issue create --project DEMO --type Task --summary "New task" --link "Blocks:DEMO-456" --link "Relates:DEMO-789"

# Add links to existing issue
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --link "is blocked by:DEMO-456"

# Add comment
$SKILL_DIR/scripts/jira.py issue comment DEMO-123 "This is a comment"

# Add private comment with security level
$SKILL_DIR/scripts/jira.py issue comment DEMO-123 "Internal note" --security-level "Internal"
```

**Arguments for `issue get`:**
- `issue_key`: Issue key (required)
- `--fields`: Comma-separated list of fields to include (uses config default if not specified)
- `--contributors`: Show unique contributors (reporter, assignee, comment authors). Opt-in; requires an extra API call.

**Arguments for `issue create`:**
- `--project`: Project key (required unless provided in `--from-file`)
- `--type`: Issue type (required unless project default configured or provided in `--from-file`)
- `--summary`: Issue summary (required unless provided in `--from-file`)
- `--description`: Issue description (cannot be used with `--from-file`)
- `--priority`: Priority name
- `--labels`: Comma-separated labels
- `--assignee`: Assignee account ID
- `--set-field NAME=VALUE`: Set a custom field (repeatable)
- `--from-file PATH`: Read issue fields and description from a markdown file (see below)
- `--link TYPE:ISSUE`: Link to another issue (repeatable). Type can be a name, outward, or inward label (e.g. `Blocks`, `is blocked by`, `Relates`)
- `--json