JIra and Confluence

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

jira-ai auth

jira-ai settings

jira-ai about

jira-ai help

Issue Management (

issue

)

jira-ai issue get <issue-id>

jira-ai issue create

jira-ai issue search <jql-query>

jira-ai issue transition <issue-id> <to-status>

jira-ai issue update <issue-id>

jira-ai issue comment <issue-id>

jira-ai issue stats <issue-ids>

jira-ai issue assign <issue-id> <account-id>

jira-ai issue label add <issue-id> <labels>

jira-ai issue label remove <issue-id> <labels>

Project Management (

project

)

jira-ai project list

jira-ai project statuses <project-key>

jira-ai project types <project-key>

User Management (

user

)

jira-ai user me

jira-ai user search [project-key]

jira-ai user worklog <person> <timeframe>

Organization Management (

org

)

jira-ai org list

jira-ai org use <alias>

jira-ai org add <alias>

jira-ai org remove <alias>

Confluence Commands (

confl

)

jira-ai confl get <url>

jira-ai confl spaces

jira-ai confl pages <space-key>

jira-ai confl create <space> <title> [parent-page]

jira-ai confl comment <url>

jira-ai confl update <url>

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