Source Code

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:

Create a .env file with the following values:

JIRA_HOST=your-domain.atlassian.net
[email protected]
JIRA_API_TOKEN=your-api-token

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 [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

jiraandconfluence