Jira

Overview

Autohand integrates with Jira Cloud and Jira Data Center to provide:

• Automatic issue creation from code comments and TODOs
• Intelligent issue triage and prioritization
• Code-to-ticket linking in commits and PRs
• Sprint planning assistance and story point estimation
• Automated status updates based on code changes

Authentication

Configure Jira authentication for your Autohand instance:

API token (Jira Cloud)

For Jira Cloud, create an API token:

1. Go to Atlassian API tokens
2. Click Create API token
3. Name it "Autohand" and click Create
4. Copy the generated token

# Set your Jira credentials
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-api-token"
export JIRA_BASE_URL="https://yourcompany.atlassian.net"

# Or configure in settings.json
autohand config set jira.email "[email protected]"
autohand config set jira.apiToken "your-api-token"
autohand config set jira.baseUrl "https://yourcompany.atlassian.net"

OAuth 2.0

For enhanced security, use OAuth 2.0:

1. Go to Jira settings > Apps > OAuth credentials
2. Create a new OAuth 2.0 integration
3. Set the callback URL to your Autohand instance
4. Configure the required scopes

Required permissions

CLI configuration

Configure Jira integration in your ~/.autohand/settings.json:

{
  "jira": {
    "enabled": true,
    "baseUrl": "${JIRA_BASE_URL}",
    "email": "${JIRA_EMAIL}",
    "apiToken": "${JIRA_API_TOKEN}",
    "defaultProject": "PROJ",
    "defaultIssueType": "Task",
    "autoLink": true,
    "todoPattern": "TODO|FIXME|HACK",
    "transitionOnMerge": true
  }
}

Configuration options

CLI commands

Autohand provides several commands for Jira interaction:

Create issues

# Create an issue from a description
autohand jira create "Fix login timeout on mobile"

# Create with specific project and type
autohand jira create "Update API docs" --project DOCS --type Story

# Create from TODO comments in code
autohand jira scan --create-issues

Link code to issues

# Link current branch to an issue
autohand jira link PROJ-123

# Create a branch for an issue
autohand jira branch PROJ-123

# View linked issues
autohand jira status

Update issues

# Transition an issue
autohand jira transition PROJ-123 "In Progress"

# Add a comment
autohand jira comment PROJ-123 "Started implementation"

# Assign to yourself
autohand jira assign PROJ-123 --me

Automation rules

Set up automatic workflows between Autohand and Jira:

Auto-transition on PR merge

When a PR referencing a Jira issue is merged:

{
  "jira": {
    "automation": {
      "onPrMerge": {
        "transition": "Done",
        "addComment": true,
        "includeCommitLog": true
      }
    }
  }
}

Auto-create issues from TODOs

Automatically create Jira issues from code comments:

{
  "jira": {
    "automation": {
      "todoToIssue": {
        "enabled": true,
        "pattern": "TODO\\(([A-Z]+-\\d+)?\\):",
        "defaultPriority": "Medium",
        "assignToCommitter": true
      }
    }
  }
}

Sprint planning assistance

Use Autohand to help with sprint planning:

# Estimate story points based on code complexity
autohand jira estimate PROJ-123

# Suggest sprint candidates based on dependencies
autohand jira sprint-suggest --points 40

# Analyze blockers and dependencies
autohand jira blockers PROJ-123

Smart commits

Autohand supports Jira Smart Commits syntax:

# Transition and log time
git commit -m "PROJ-123 #done #time 2h Fixed login bug"

# Add comment
git commit -m "PROJ-123 #comment Code review complete"

# Multiple commands
git commit -m "PROJ-123 PROJ-124 #resolve #time 1h30m Both issues fixed"

Smart commit commands

Jira Data Center

For self-hosted Jira Data Center installations:

{
  "jira": {
    "type": "datacenter",
    "baseUrl": "https://jira.yourcompany.com",
    "username": "${JIRA_USERNAME}",
    "password": "${JIRA_PASSWORD}",
    "verifySsl": true
  }
}

Personal access token

For Data Center 8.14+, use personal access tokens:

1. Go to Profile > Personal Access Tokens
2. Click Create token
3. Set an expiry date and click Create
4. Copy the generated token

{
  "jira": {
    "type": "datacenter",
    "baseUrl": "https://jira.yourcompany.com",
    "personalAccessToken": "${JIRA_PAT}"
  }
}

Webhooks

Configure webhooks to trigger Autohand on Jira events:

1. Go to Jira settings > System > Webhooks
2. Click Create a WebHook
3. Set the URL to your Autohand webhook endpoint
4. Select events: Issue created, Issue updated, Sprint started
5. Save the webhook

Supported events

Troubleshooting

Authentication errors

• Verify your API token has not expired
• Check that the email matches your Atlassian account
• Ensure the base URL includes the protocol (https://)

Permission errors

• Verify you have access to the target project
• Check that your role allows issue creation/editing
• For Data Center, ensure your account is not restricted

Smart commits not working

• Ensure DVCS connector is configured in Jira
• Verify issue keys are in the correct format (PROJ-123)
• Check that Smart Commits are enabled for your project