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
   [email protected]
   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

Issue Management (issue)

Project Management (project)

User Management (user)

Organization Management (org)

Confluence Commands (confl)

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 [email protected] 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