Jira Integration

Pilot connects to Jira Cloud and Jira Server to receive issues and post status updates. When an issue is labeled with the pilot tag, Pilot implements it and links the resulting PR back to the Jira issue.

Setup

1. Create a Jira API Token

Jira Cloud:

1. Go to id.atlassian.com/manage-profile/security/api-tokens 
2. Click Create API token
3. Copy the token

Jira Server:

1. Go to Profile → Personal Access Tokens
2. Create a new token

2. Configure Pilot

# ~/.pilot/config.yaml
jira:
  enabled: true
  platform: cloud            # "cloud" or "server"
  base_url: https://your-company.atlassian.net
  username: pilot@company.com
  api_token: ${JIRA_API_TOKEN}
  pilot_label: pilot
  transitions:
    in_progress: "21"        # Jira transition ID
    done: "31"               # Jira transition ID

Configuration Reference

Finding Transition IDs

Transition IDs vary by project and workflow. To find yours:

curl -u user@example.com:$JIRA_API_TOKEN \
  https://your-company.atlassian.net/rest/api/3/issue/PROJ-1/transitions

If transition IDs are not configured, Pilot falls back to matching by status name (“In Progress”, “Done”).

Webhooks

Setting Up Jira Webhooks

1. Go to Jira → Settings → System → Webhooks
2. Create a new webhook pointing to https://your-pilot.example.com/webhooks/jira
3. Select events: Issue created, Issue updated

Supported Events

Webhook Security

Jira webhooks are verified using HMAC-SHA256 signatures via the X-Hub-Signature header. If webhook_secret is not set, all webhooks are accepted.

API Differences: Cloud vs Server

Pilot automatically detects the platform from configuration and uses the correct API version and content format.

Issue Type Mapping

Priority Mapping

Task Conversion

Jira issues are converted to Pilot tasks with the following mapping:

Reliability Features (v2.10.0)

ProcessedStore — Duplicate Prevention

The Jira poller tracks which issues have been processed using a persistent store backed by SQLite. This prevents duplicate task dispatch across restarts, hot upgrades, and crash recovery.

On startup the poller loads previously processed issue keys. After successful execution an issue is marked as processed; if execution fails, the mark is removed so the issue is retried on the next poll cycle.

No additional configuration is required — ProcessedStore is wired automatically when using the default Pilot setup.

Autopilot Pipeline via OnPRCreated

Starting in v2.10.0, Jira-sourced tasks have full autopilot parity with GitHub issues. When Pilot creates a PR for a Jira issue, the OnPRCreated callback wires it into the autopilot controller, enabling:

• CI monitoring — Pilot watches the PR’s CI status and posts updates back to the Jira issue
• Auto-merge — PRs that pass all quality gates are merged automatically (when enabled)
• Feedback loop — CI failures trigger automatic fix attempts

This brings Jira to the same level of automation previously available only for GitHub-sourced tasks.

Status Transitions

Pilot updates Jira issue status as it works:

PR Linking

When Pilot creates a PR, it adds a remote link to the Jira issue pointing to the GitHub/GitLab PR URL, visible in the issue’s “Links” section.