jira-skill

🥈Silver

Automate Jira tasks with Python scripts. Integrates with MCP config and wiki markup. Works with Claude Code. Ideal for operations teams managing projects and workflows.

4460Updated 1mo ago

Intermediate30min to implementautomation

Saves ~135 min per use

Quick InstallView Source

git clone https://github.com/netresearch/jira-skill.git

Works with:

Claude

Overview

About This Skill

Automate Jira tasks with Python scripts. Integrates with MCP config and wiki markup. Works with Claude Code. Ideal for operations teams managing projects and workflows.

How to Use

[{"step":"Install prerequisites","action":"Run `pip install jira python-dotenv` and ensure you have Python 3.8+. Set up a Jira API token at https://id.atlassian.com/manage-profile/security/api-tokens and store it in a `.env` file as `JIRA_API_TOKEN=your_token_here`.","tip":"Use `python-dotenv` to securely manage credentials. Never commit API tokens to version control."},{"step":"Configure the script","action":"Replace placeholders in the template with your specific values: JIRA_URL, PROJECT_KEY, TRANSITION_ID, and ISSUE_FILTER. Use Jira's REST API browser to find transition IDs for your workflow.","tip":"Test your JQL filter in Jira's issue search first to verify it returns the correct issues before automating."},{"step":"Test in staging","action":"Run the script against a test project or staging Jira instance first. Use a small subset of issues (e.g., 5-10) to verify behavior. Check the log file after execution.","tip":"Add `maxResults=5` to your ISSUE_FILTER temporarily to limit test scope. Verify transitions in the Jira UI before running on production."},{"step":"Schedule execution","action":"For regular tasks, set up a cron job (Linux) or Task Scheduler (Windows) to run the script periodically. For complex workflows, consider using Jira Automation rules instead.","tip":"For production use, wrap the script in a Docker container with proper logging and monitoring. Consider adding Slack/email notifications for failures."},{"step":"Monitor and refine","action":"Review the log file after each run to identify issues. Adjust retry logic, error handling, or transition criteria based on observed patterns.","tip":"Implement a dry-run mode by adding a `--dry-run` flag that logs actions without performing them. This is safer for production changes."}]

Setup & Installation

Quick Install

No install command available. Check the GitHub repository for manual installation instructions.

Alternative Install (Git Clone)

git clone https://github.com/netresearch/jira-skill

Requirements

Claude Code or compatible AI agent
Works with: Claude

Quick Start Guide

Install the Skill

Copy the install command above and run it in your terminal.

Open Your AI Agent

Launch Claude Code, Cursor, or your preferred AI coding agent.

Try It Out

Use the prompt template or examples below to test the skill.

Customize

Adapt the skill to your specific use case and workflow.

Usage Examples

Prompt Template

Write a Python script using the Jira Python library to automate [TASK] in Jira. The script should: 1) Connect to the Jira instance using [JIRA_URL] and [API_TOKEN], 2) Perform [SPECIFIC_ACTION] on [ISSUE_KEYS_OR_FILTER], 3) Log results to [LOG_FILE_PATH], and 4) Handle errors gracefully with retry logic for [MAX_RETRIES] attempts. Include comments explaining each step and ensure the script follows [BEST_PRACTICES]. Test the script in a staging environment first.

Example Output

```python
# Jira Automation Script: Bulk Transition Issues to 'In Progress'
# Created: 2024-05-15 | Version: 1.2
# Purpose: Automate transitioning backlog issues to active sprint work

import os
import logging
from jira import JIRA
from jira.exceptions import JIRAError

# Configuration - Replace placeholders with your values
JIRA_URL = "https://your-domain.atlassian.net"
API_TOKEN = os.getenv("JIRA_API_TOKEN")  # Requires env var setup
PROJECT_KEY = "PROJ"
TRANSITION_ID = "11"  # ID for 'Start Progress' transition
ISSUE_FILTER = f"project = {PROJECT_KEY} AND status = 'To Do' ORDER BY created ASC"
LOG_FILE_PATH = "/var/log/jira/bulk_transition.log"
MAX_RETRIES = 3

# Setup logging
logging.basicConfig(
    filename=LOG_FILE_PATH,
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

def connect_to_jira():
    """Establish connection to Jira instance"""
    try:
        jira = JIRA(
            server=JIRA_URL,
            token_auth=API_TOKEN,
            options={'verify': False}  # For self-signed certs in staging
        )
        logging.info("Successfully connected to Jira")
        return jira
    except JIRAError as e:
        logging.error(f"Jira connection failed: {str(e)}")
        raise

def get_issues_to_transition(jira):
    """Fetch issues matching the filter criteria"""
    try:
        issues = jira.search_issues(ISSUE_FILTER, maxResults=50)
        logging.info(f"Found {len(issues)} issues to transition")
        return issues
    except JIRAError as e:
        logging.error(f"Issue search failed: {str(e)}")
        raise

def transition_issue(jira, issue, transition_id):
    """Attempt to transition a single issue with retry logic"""
    for attempt in range(1, MAX_RETRIES + 1):
        try:
            jira.transition_issue(issue, transition_id)
            logging.info(f"Transitioned {issue.key} to 'In Progress'")
            return True
        except JIRAError as e:
            logging.warning(f"Attempt {attempt} failed for {issue.key}: {str(e)}")
            if attempt == MAX_RETRIES:
                logging.error(f"Max retries reached for {issue.key}")
                return False
            time.sleep(2 ** attempt)  # Exponential backoff

def main():
    """Main execution function"""
    try:
        jira = connect_to_jira()
        issues = get_issues_to_transition(jira)
        
        success_count = 0
        for issue in issues:
            if transition_issue(jira, issue, TRANSITION_ID):
                success_count += 1
        
        logging.info(f"Process completed: {success_count}/{len(issues)} issues transitioned")
        print(f"Success! {success_count} issues transitioned. See {LOG_FILE_PATH} for details")
        
    except Exception as e:
        logging.critical(f"Script failed: {str(e)}", exc_info=True)
        print(f"Error occurred. Check {LOG_FILE_PATH} for details")
        raise

if __name__ == "__main__":
    import time  # Required for retry logic
    main()
```

**Execution Results:**
```
2024-05-15 14:30:22,123 - INFO - Successfully connected to Jira
2024-05-15 14:30:25,456 - INFO - Found 42 issues to transition
2024-05-15 14:30:28,789 - INFO - Transitioned PROJ-123 to 'In Progress'
2024-05-15 14:30:31,234 - INFO - Transitioned PROJ-124 to 'In Progress'
2024-05-15 14:30:33,567 - WARNING - Attempt 1 failed for PROJ-125: Issue does not exist
2024-05-15 14:30:36,890 - INFO - Transitioned PROJ-125 to 'In Progress'
...
2024-05-15 14:32:10,345 - INFO - Process completed: 40/42 issues transitioned
```

**Output File (bulk_transition.log):**
```
2024-05-15 14:30:22 - INFO - Successfully connected to Jira
2024-05-15 14:30:25 - INFO - Found 42 issues to transition
2024-05-15 14:30:28 - INFO - Transitioned PROJ-123 to 'In Progress'
2024-05-15 14:30:31 - INFO - Transitioned PROJ-124 to 'In Progress'
2024-05-15 14:30:33 - WARNING - Attempt 1 failed for PROJ-125: Issue does not exist
2024-05-15 14:30:36 - INFO - Transitioned PROJ-125 to 'In Progress'
2024-05-15 14:32:10 - INFO - Process completed: 40/42 issues transitioned
2024-05-15 14:32:10 - ERROR - Max retries reached for PROJ-126
2024-05-15 14:32:10 - ERROR - Max retries reached for PROJ-127
```