Jira-AI Skill

The jira-ai skill provides comprehensive command-line access to Atlassian Jira and Confluence platforms, allowing agents to manage issues, projects, users, and documentation efficiently.

Installation

To install jira-ai, run:

npm install -g jira-ai

Authentication Setup

Before using jira-ai, you need to configure your Jira credentials:

1. Create a .env file with the following values:

   JIRA_HOST=your-domain.atlassian.net
   JIRA_USER_EMAIL=your-email@example.com
   JIRA_API_TOKEN=your-api-token
   

2. Authenticate using the .env file:

   jira-ai auth --from-file path/to/.env
   

Configuration

You can manage settings using the settings command:

jira-ai settings --help

Apply settings from a YAML file:

jira-ai settings --apply my-settings.yaml

Validate settings:

jira-ai settings --validate my-settings.yaml

Commands Overview

Top-Level Commands

| Command | Description | | :--- | :--- | | jira-ai auth | Set up Jira authentication credentials | | jira-ai settings | View, validate, or apply configuration settings | | jira-ai about | Show information about the tool | | jira-ai help | Display help for commands |

Issue Management (issue)

| Command | Description | | :--- | :--- | | jira-ai issue get <issue-id> | Retrieve comprehensive issue data | | jira-ai issue create | Create a new Jira issue | | jira-ai issue search <jql-query> | Execute a JQL search query | | jira-ai issue transition <issue-id> <to-status> | Change the status of a Jira issue | | jira-ai issue update <issue-id> | Update a Jira issue's description | | jira-ai issue comment <issue-id> | Add a new comment to a Jira issue | | jira-ai issue stats <issue-ids> | Calculate time-based metrics for issues | | jira-ai issue assign <issue-id> <account-id> | Assign or reassign a Jira issue | | jira-ai issue label add <issue-id> <labels> | Add labels to a Jira issue | | jira-ai issue label remove <issue-id> <labels> | Remove labels from a Jira issue |

Project Management (project)

| Command | Description | | :--- | :--- | | jira-ai project list | List all accessible Jira projects | | jira-ai project statuses <project-key> | Fetch workflow statuses for a project | | jira-ai project types <project-key> | List issue types available for a project |

User Management (user)

| Command | Description | | :--- | :--- | | jira-ai user me | Show profile details for authenticated user | | jira-ai user search [project-key] | Search and list users | | jira-ai user worklog <person> <timeframe> | Retrieve worklogs for a user |

Organization Management (org)

| Command | Description | | :--- | :--- | | jira-ai org list | List all saved Jira organization profiles | | jira-ai org use <alias> | Switch the active Jira organization profile | | jira-ai org add <alias> | Add a new Jira organization profile | | jira-ai org remove <alias> | Delete credentials for an organization |

Confluence Commands (confl)

| Command | Description | | :--- | :--- | | jira-ai confl get <url> | Download Confluence page content | | jira-ai confl spaces | List all allowed Confluence spaces | | jira-ai confl pages <space-key> | Display pages within a space | | jira-ai confl create <space> <title> [parent-page] | Create a new Confluence page | | jira-ai confl comment <url> | Add a comment to a Confluence page | | jira-ai confl update <url> | Update a Confluence page |

Usage Examples

Search for issues assigned to the current user

jira-ai issue search "assignee = currentUser()"

Get details of a specific issue

jira-ai issue get PROJ-123

Create a new issue

jira-ai issue create --project "PROJ" --summary "New task" --issuetype "Story"

Transition an issue to a new status

jira-ai issue transition PROJ-123 "In Progress"

Add a comment to an issue

jira-ai issue comment PROJ-123 --file comment.md

List all projects

jira-ai project list

Get worklogs for a user

jira-ai user worklog john.doe@example.com 2w

Configuration Options

The jira-ai tool supports extensive configuration through settings files. You can define:

• Allowed Jira projects
• Allowed commands
• Allowed Confluence spaces
• Default behaviors for various operations

Example settings structure:

defaults:
  allowed-jira-projects:
    - all                     # Allow all projects
  allowed-commands:
    - all                     # Allow all commands
  allowed-confluence-spaces:
    - all                     # Allow all Confluence spaces

organizations:
  work:
    allowed-jira-projects:
      - PROJ                  # Allow specific project
      - key: PM               # Project-specific config
        commands:
          - issue.get         # Only allow reading issues
        filters:
          participated:
            was_assignee: true
    allowed-commands:
      - issue                 # All issue commands
      - project.list          # Only project list
      - user.me               # Only user me
    allowed-confluence-spaces:
      - DOCS

Benefits

• Efficient API Usage: Minimizes the number of API calls needed to perform common operations
• Batch Operations: Process multiple items at once to reduce API usage
• Smart Filtering: Use JQL to retrieve only the specific data needed
• Local Processing: Handle operations locally before sending targeted requests to Jira
• Configuration-Based Access Control: Define allowed commands and projects to prevent unauthorized operations
• Specific Command Targeting: Get only the information needed, reducing payload sizes and API usage

Security Considerations

• Store API tokens securely in environment files
• Use configuration-based access controls to limit operations
• Regularly rotate API tokens
• Limit permissions to the minimum required for operations