---
title: "Jira Integration"
source: https://docs.autohand.ai/integrations/jira
---

# Jira

Connect Autohand to Jira for automated issue management, intelligent triage, and seamless code-to-ticket linking.

## 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](https://id.atlassian.com/manage-profile/security/api-tokens)
2.  Click **Create API token**
3.  Name it "Autohand" and click **Create**
4.  Copy the generated token

``` bash
# Set your Jira credentials
export JIRA_EMAIL="your-email@company.com"
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 "your-email@company.com"
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

| Scope | Purpose |
|---|---|
| read:jira-work | Read issues, projects, and boards |
| write:jira-work | Create and update issues |
| read:jira-user | Read user information for assignments |
| manage:jira-configuration | Access project settings (optional) |

## CLI configuration

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

``` 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

| Option | Description | Default |
|---|---|---|
| enabled | Enable Jira integration | true |
| baseUrl | Jira instance URL | - |
| email | Atlassian account email | - |
| apiToken | API token for authentication | - |
| defaultProject | Default project key for new issues | - |
| defaultIssueType | Default issue type | Task |
| autoLink | Auto-link commits to issues | true |
| todoPattern | Regex pattern for TODO detection | TODO\|FIXME |
| transitionOnMerge | Transition issues when PRs merge | true |

## CLI commands

Autohand provides several commands for Jira interaction:

### Create issues

``` bash
# 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

``` bash
# 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

``` bash
# 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:

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

### Auto-create issues from TODOs

Automatically create Jira issues from code comments:

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

### Sprint planning assistance

Use Autohand to help with sprint planning:

``` bash
# 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:

``` bash
# 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

| Command | Description | Example |
|---|---|---|
| #comment | Add a comment | #comment Fixed in release 2.0 |
| #time | Log work time | #time 2h 30m |
| #<transition> | Transition issue | #done, #in-progress |

## Jira Data Center

For self-hosted Jira Data Center installations:

``` json
{
  "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

``` json
{
  "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

| Event | Autohand action |
|---|---|
| Issue created | Analyze and suggest implementation approach |
| Issue updated | Update related code comments |
| Issue assigned | Notify in Slack (if configured) |
| Sprint started | Generate sprint summary |

## 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