/setup

/jira:setup - Configure JIRA Credentials and Settings

Interactive configuration wizard for jira plugin.

Task

Set up JIRA connection credentials and default settings for the jira plugin.

Step 0: Resolve Plugin Root

Extract PLUGIN_ROOT from the <jira-context> system reminder injected by the UserPromptSubmit hook. Use the value from <plugin-root>.

Then invoke the setup-plugin-env skill to ensure the venv is ready.

---

Step 1: Check for Existing Configuration

Check if configuration already exists:

CONFIG_FILE="$HOME/.claude/jira.local.md"

if [ -f "$CONFIG_FILE" ]; then
    echo "📋 Found existing configuration at $CONFIG_FILE"

    # Check if --reset flag was provided
    if [[ "$*" == *"--reset"* ]]; then
        echo "🔄 Resetting configuration..."
    else
        echo ""
        echo "Configuration already exists. Options:"
        echo "1. Keep existing configuration"
        echo "2. Update specific settings"
        echo "3. Reset all settings"
        echo ""
        # Continue to interactive wizard
    fi
else
    echo "📝 No existing configuration found. Starting setup wizard..."
fi

Step 2: Interactive Configuration Wizard

Use AskUserQuestion to gather configuration values:

Question 1: JIRA Server URL

• Header: "JIRA Server"
• Question: "What is your JIRA server URL?"
• Options:
  • Label: "Red Hat JIRA (issues.redhat.com)" Description: "Use https://issues.redhat.com"
  • Label: "Custom URL" Description: "Enter a different JIRA server URL"
• Store answer in: jira_url

Question 2: Authentication Token

• Header: "API Token"
• Question: "Enter your JIRA Personal Access Token (PAT)"
• Note: This will be asked via "Other" text input since it's sensitive
• Guidance: "Create a PAT in JIRA under Profile → Personal Access Tokens"
• Store answer in: jira_pat

Question 3: Default Username

• Header: "Username"
• Question: "What is your JIRA username?"
• Options:
  • Label: "Auto-detect from API" Description: "Query JIRA API after connection test"
  • Label: "Enter manually" Description: "Specify username now"
• Store answer in: default_username

Question 4: Default Project

• Header: "Project"
• Question: "Which JIRA project do you primarily work with?"
• Options:
  • Label: "RHAISTRAT" Description: "Red Hat AI Strategic Features"
  • Label: "RHOAISTRAT" Description: "Red Hat OpenShift AI Strategic Features"
  • Label: "RHAIENG" Description: "Red Hat AI Engineering"
  • Label: "Other" Description: "Enter project key manually"
• Store answer in: default_project

Question 5: Current Sprint (optional)

• Header: "Sprint"
• Question: "What is your current sprint ID or name? (optional)"
• Note: Can be left blank and set later
• Store answer in: current_sprint_id

Step 4: Test Connection

Before saving, test the JIRA connection:

VENV_PYTHON=".claude/jira/venv/bin/python"

echo ""
echo "🔍 Testing JIRA connection..."

# Create temporary config for testing
TEMP_CONFIG=$(mktemp)
cat > "$TEMP_CONFIG" << EOF
---
jira_url: "$jira_url"
jira_pat: "$jira_pat"
---
EOF

# Set environment variables for test
export JIRA_URL="$jira_url"
export JIRA_API_TOKEN="$jira_pat"

# Test connection
TEST_RESULT=$("$VENV_PYTHON" "$PLUGIN_ROOT/scripts/jira_client.py" test_connection 2>&1)

if echo "$TEST_RESULT" | grep -q '"success": true'; then
    echo "✅ Connection successful!"

    # Extract username if auto-detect selected
    if [ "$default_username" == "Auto-detect from API" ] || [ -z "$default_username" ]; then
        default_username=$(echo "$TEST_RESULT" | grep -o '"user": "[^"]*"' | cut -d'"' -f4)
        echo "   Detected username: $default_username"
    fi
else
    echo "❌ Connection failed!"
    echo ""
    echo "Error details:"
    echo "$TEST_RESULT"
    echo ""
    echo "Please verify your credentials and try again."
    exit 1
fi

# Clean up temp config
rm -f "$TEMP_CONFIG"

Step 5: Save Configuration

Create or update .claude/jira.local.md with YAML frontmatter:

CONFIG_FILE="$HOME/.claude/jira.local.md"
CONFIG_DIR="$(dirname "$CONFIG_FILE")"

# Ensure .claude directory exists
mkdir -p "$CONFIG_DIR"

# Create configuration file
cat > "$CONFIG_FILE" << EOF
---
jira_url: "$jira_url"
jira_pat: "$jira_pat"
default_username: "$default_username"
default_project: "$default_project"
current_sprint_id: "$current_sprint_id"
cache_duration: 14400
default_jql_filters: "assignee = currentUser() AND resolution = Unresolved ORDER BY priority DESC"
project_repo_mappings: {}
---

# jira Plugin Configuration

This file stores your JIRA connection settings and preferences for the jira plugin.

## Credentials

- **JIRA URL:** $jira_url
- **Username:** $default_username

## Defaults

- **Project:** $default_project
- **Sprint:** ${current_sprint_id:-"(not set)"}

## Cache Settings

- **Duration:** 14400 seconds (4 hours)

## Repository Mappings

Use \`/jira:repo-add\`, \`/jira:repo-remove\`, and \`/jira:repo-list\` to manage project→repository mappings for code analysis.

## Security Note

This file contains your Personal Access Token. Keep it secure:
- Do not commit to version control
- Do not share with others
- Rotate tokens regularly

EOF

chmod 600 "$CONFIG_FILE"

echo ""
echo "✅ Configuration saved to $CONFIG_FILE"
echo "   (File permissions set to 600 for security)"

Step 6: Display Summary

Show configuration summary:

echo ""
echo "📊 Configuration Summary"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "JIRA Server:     $jira_url"
echo "Username:        $default_username"
echo "Default Project: $default_project"
echo "Current Sprint:  ${current_sprint_id:-(not set)}"
echo "Cache Duration:  14400 seconds (4 hours)"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "✨ Setup complete! You can now use jira commands:"
echo ""
echo "   /jira:my-issues     - List your assigned issues"
echo "   /jira:sprint        - List issues in current sprint"
echo "   /jira:summarize KEY - Summarize a JIRA issue"
echo ""
echo "To update settings later, run: /jira:setup --reset"
echo ""

Step 7: Environment Variable Alternative (Optional)

Inform user about environment variable option:

echo "💡 Alternative: Environment Variables"
echo ""
echo "Instead of storing credentials in the config file, you can use environment variables:"
echo ""
echo "   export JIRA_URL=\"$jira_url\""
echo "   export JIRA_API_TOKEN=\"your-token-here\""
echo "   export JIRA_AUTH_TYPE=\"bearer\""
echo ""
echo "Environment variables override config file settings."
echo ""

Error Handling

If connection test fails:

• Display clear error message
• Suggest common issues:
  • Invalid PAT (check token is active)
  • Incorrect URL (verify server address)
  • Network issues (check connectivity)
  • Insufficient permissions (verify token has required scopes)
• Do not save configuration
• Offer to retry

If file write fails:

• Check directory permissions
• Suggest manual creation of .claude/ directory
• Display configuration values for manual entry

If --reset flag is provided:

• Confirm with user before deleting existing config
• Back up existing config to .claude/jira.local.md.bak

Notes

• Personal Access Token is stored in YAML frontmatter (keep file secure)
• File permissions are set to 600 (owner read/write only)
• Configuration can be updated anytime by running /jira:setup again
• Repository mappings are initially empty (use /jira:repo-add to configure)

Security Best Practices

1. Never commit .claude/jira.local.md to version control
2. Rotate tokens regularly (every 90 days recommended)
3. Use minimal permissions for PAT (only what's needed)
4. Revoke unused tokens in JIRA settings
5. Monitor token usage in JIRA audit logs