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: ```bash 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: ```bash jira-ai auth --from-file path/to/.env ```

## Configuration

You can manage settings using the settings command:

```bash jira-ai settings --help ```

Apply settings from a YAML file: ```bash jira-ai settings --apply my-settings.yaml ```

Validate settings: ```bash 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 ```bash jira-ai issue search "assignee = currentUser()" ```

### Get details of a specific issue ```bash jira-ai issue get PROJ-123 ```

### Create a new issue ```bash jira-ai issue create --project "PROJ" --summary "New task" --issuetype "Story" ```

### Transition an issue to a new status ```bash jira-ai issue transition PROJ-123 "In Progress" ```

### Add a comment to an issue ```bash jira-ai issue comment PROJ-123 --file comment.md ```

### List all projects ```bash jira-ai project list ```

### Get worklogs for a user ```bash 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: ```yaml 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