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
.envfile with the following values:JIRA_HOST=your-domain.atlassian.net JIRA_USER_EMAIL=your-email@example.com 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 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