alanalvestech/jira

/jira

Connect to Jira Cloud to manage projects, issues, sprints, boards and more. Pure Ruby, zero gems — stdlib only.

Structure

scripts/
├── auth.rb          # Basic Auth + jira_request helper (required by all scripts)
├── check_setup.rb   # Check if config exists (outputs OK or SETUP_NEEDED)
├── save_config.rb   # Save and validate domain, email and API token
├── projects.rb      # List projects
├── project.rb       # Get project details
├── issues.rb        # Search issues using JQL
├── issue.rb         # Get issue details
├── create_issue.rb  # Create an issue
├── update_issue.rb  # Update an issue
├── transitions.rb   # List available transitions for an issue
├── transition.rb    # Transition an issue (change status)
├── comments.rb      # List comments on an issue
├── add_comment.rb   # Add a comment to an issue
├── assign.rb        # Assign an issue to a user
├── boards.rb        # List boards (Agile)
└── sprints.rb       # List sprints for a board

Setup (check before using)

ruby ~/.claude/skills/jira/scripts/check_setup.rb

If the output is OK, proceed to the Flow section.

If the output is SETUP_NEEDED, guide the user step by step. Present ONE step at a time, wait for the user to confirm before moving to the next.

Step 1 — Ask the user for their Jira domain:

What is your Jira Cloud domain? For example, if you access Jira at https://mycompany.atlassian.net, the domain is mycompany.

Step 2 — Ask the user to create an API token:

Create an API token at: https://id.atlassian.com/manage-profile/security/api-tokens

Click Create API token, give it a name (e.g. "hitank"), and copy the token. Also confirm your Atlassian account email.

Paste the email and token here.

Step 3 — When the user provides all three values, save them:

ruby ~/.claude/skills/jira/scripts/save_config.rb 'DOMAIN' 'EMAIL' 'TOKEN'

If the script outputs an error, the config is invalid. Ask the user to double-check and try again.

If setup is not complete, DO NOT proceed to the Flow. Complete all steps first.

Flow

The argument $ARGUMENTS may contain a project key or issue key.

Step 1: List projects

ruby ~/.claude/skills/jira/scripts/projects.rb

Present the projects. If $ARGUMENTS matches a project key, use that project. Otherwise ask which project to work with.

Step 2: Search issues

ruby ~/.claude/skills/jira/scripts/issues.rb 'project = PROJECT_KEY ORDER BY updated DESC'

Present the issues and ask what the user wants to do.

Step 3: Actions

Get issue details:

ruby ~/.claude/skills/jira/scripts/issue.rb ISSUE_KEY

Search with JQL:

ruby ~/.claude/skills/jira/scripts/issues.rb 'project = MYPROJ AND status = "In Progress"'
ruby ~/.claude/skills/jira/scripts/issues.rb 'assignee = currentUser() ORDER BY priority DESC' --max 50

Create an issue (requires user confirmation):

Ask the user to confirm the details before creating.

ruby ~/.claude/skills/jira/scripts/create_issue.rb PROJECT_KEY "Issue summary"
ruby ~/.claude/skills/jira/scripts/create_issue.rb PROJECT_KEY "Fix login bug" --type Bug --priority High --description "Detailed description"

Update an issue (requires user confirmation):

Show current issue details first, then ask what to change.

ruby ~/.claude/skills/jira/scripts/update_issue.rb ISSUE_KEY '{"summary":"New title","priority":{"name":"High"}}'

Transition an issue (requires user confirmation):

First list available transitions, then ask which one to apply.

ruby ~/.claude/skills/jira/scripts/transitions.rb ISSUE_KEY
ruby ~/.claude/skills/jira/scripts/transition.rb ISSUE_KEY TRANSITION_ID

Assign an issue (requires user confirmation):

ruby ~/.claude/skills/jira/scripts/assign.rb ISSUE_KEY ACCOUNT_ID
ruby ~/.claude/skills/jira/scripts/assign.rb ISSUE_KEY unassign

List comments:

ruby ~/.claude/skills/jira/scripts/comments.rb ISSUE_KEY

Add a comment (requires user confirmation):

ruby ~/.claude/skills/jira/scripts/add_comment.rb ISSUE_KEY "Comment text here"

List boards (Agile):

ruby ~/.claude/skills/jira/scripts/boards.rb

List sprints:

ruby ~/.claude/skills/jira/scripts/sprints.rb BOARD_ID
ruby ~/.claude/skills/jira/scripts/sprints.rb BOARD_ID --state active

Notes

• Pure Ruby, zero gems — stdlib only (json, net/http, uri, base64, fileutils)
• Auth via Basic Auth (email + API token)
• Config file: ~/.config/jira/config.json (outside the repo, never commit)
• Creating, updating, transitioning, and assigning issues require explicit user confirmation
• Adding comments requires user confirmation
• Jira Cloud API v3 uses Atlassian Document Format (ADF) for descriptions and comments
• JQL (Jira Query Language) is used for searching issues
• Base URL: https://DOMAIN.atlassian.net/rest/api/3
• Agile URL: https://DOMAIN.atlassian.net/rest/agile/1.0