Integrations

Jira / Atlassian

Connect to Jira Cloud, Jira Server, or Jira Data Center. Manage issues, run JQL queries, transition statuses, and work with sprints — all from your AI client.

Deployment types

Jira Cloud

Hostyoursite.atlassian.net

AuthAPI token (id.atlassian.com)

Most common. Free tier available.

Jira Server

HostSelf-hosted URL

AuthPersonal Access Token (PAT)

On-premises, older versions.

Jira Data Center

HostSelf-hosted URL

AuthPersonal Access Token (PAT)

Enterprise on-premises. Same API as Server.

Jira Cloud — API token

API tokens are tied to your Atlassian account. You use your account email as the username and the token as the password in Basic auth. Tokens are not project-scoped — they have the same permissions as your account.

1Go to id.atlassian.com → Security → API tokens

2Click Create API token. Give it a label (e.g. Conductor).

3Copy the token immediately — it's only shown once.

4Your base URL is https://YOURSITE.atlassian.net — find YOURSITE in your browser when logged in.

5Your email is the one you use to log in to Atlassian.

Jira Server / Data Center — Personal Access Token

PATs were introduced in Jira Server 8.14 and Data Center 8.14. If you're on an older version, use Basic auth (username + password) instead.

1Log in to Jira Server. Click your profile icon → Personal Access Tokens.

2Click Create token. Give it a name and optional expiry.

3Copy the token. In Conductor config, use personalAccessToken (not apiToken + email).

4If on Jira < 8.14: use Basic auth with username and password fields instead.

Configuration

Jira Cloud — ~/.conductor/config.json

// ~/.conductor/config.json
{
  "plugins": {
    "jira": {
      "enabled": true,
      "deployment": "cloud",
      "baseUrl": "https://yoursite.atlassian.net",
      "email": "you@yourcompany.com",
      "apiToken": "your-api-token-here"
    }
  }
}

Jira Server / Data Center

// ~/.conductor/config.json — Jira Server / Data Center
{
  "plugins": {
    "jira": {
      "enabled": true,
      "deployment": "server",
      "baseUrl": "https://jira.yourcompany.com",
      "personalAccessToken": "your-PAT-here"
    }
  }
}

Available tools

Tool	Description
`jira.issue.get`	Get full issue details by key (e.g. PROJ-123)
`jira.issue.create`	Create an issue with type, summary, description, fields
`jira.issue.update`	Update summary, description, assignee, priority, custom fields
`jira.issue.transition`	Move issue to a new status by transition ID
`jira.issue.comment`	Add a comment to an issue
`jira.issue.search`	Run a JQL query and return matching issues
`jira.issue.assign`	Assign an issue to a user (by accountId or email)
`jira.issue.link`	Link two issues (blocks, is blocked by, relates to)
`jira.issue.attachment`	Upload a file attachment to an issue
`jira.issue.transitions`	List available transitions for an issue
`jira.project.list`	List all accessible projects
`jira.project.get`	Get project details including issue types and components
`jira.sprint.list`	List sprints in a board
`jira.sprint.get`	Get sprint details including dates and state
`jira.sprint.issues`	Get all issues in a sprint
`jira.board.list`	List all boards (scrum and kanban)
`jira.user.search`	Search users by email or display name
`jira.user.me`	Get the authenticated user's account details

JQL — Jira Query Language

jira.issue.search takes a JQL string. JQL is Jira's SQL-like query language. Common patterns:

JQL examples

-- Issues assigned to me, open
assignee = currentUser() AND resolution = Unresolved

-- Issues in a sprint
sprint in openSprints() AND project = "MYPROJ"

-- Recently updated bugs
issuetype = Bug AND updated >= -7d ORDER BY updated DESC

-- Issues with a specific label
labels = "backend" AND status != Done

-- Epic children
"Epic Link" = PROJ-123

-- Issues created this week
created >= startOfWeek() ORDER BY created DESC

-- Blockers
priority = Highest AND resolution = Unresolved

-- Issues in multiple projects
project in (PROJ1, PROJ2) AND status = "In Progress"

Field	Operators	Notes
`project`	`=, !=, in, not in`	Use project key (PROJ), not name
`status`	`=, !=, in, changed`	Use exact status name in quotes
`assignee`	`=, is EMPTY`	currentUser() for the authed user
`priority`	`=, !=, in`	Highest, High, Medium, Low, Lowest
`issuetype`	`=, !=, in`	Story, Bug, Task, Epic, Sub-task
`created / updated`	`>=, <=, >, <`	-7d, startOfWeek(), startOfMonth()
`sprint`	`in`	openSprints(), closedSprints(), or sprint name
`labels`	`=, in, is EMPTY`	Exact label string, case-sensitive

Transitions

To transition an issue, you need the transition ID, not the name. IDs differ per project and per workflow. Always look them up first.

Find transition IDs

# Find transition IDs for an issue
conductor jira transitions --issue PROJ-123

# Output:
# ID    NAME
# 11    To Do
# 21    In Progress
# 31    In Review
# 41    Done

Custom fields

Jira custom fields have IDs like customfield_10016. Map them to friendly names in config so Conductor can reference them by name.

config — custom field mapping

// Custom fields use IDs like customfield_10001
// Find them via: GET /rest/api/3/field

// In Conductor config — map friendly names to field IDs
{
  "plugins": {
    "jira": {
      "customFields": {
        "storyPoints": "customfield_10016",
        "epicLink":    "customfield_10014",
        "sprint":      "customfield_10020",
        "team":        "customfield_10001"
      }
    }
  }
}

create issue with custom fields

// Create an issue with custom fields
{
  "name": "jira.issue.create",
  "arguments": {
    "project": "PROJ",
    "summary": "Implement OAuth flow",
    "issuetype": "Story",
    "priority": "High",
    "assignee": "user@company.com",
    "labels": ["backend", "auth"],
    "customFields": {
      "storyPoints": 5,
      "sprint": "PROJ Sprint 14"
    }
  }
}

Finding custom field IDs

In Jira Cloud: Admin → Issues → Custom fields → click the field → the URL contains the ID.
Via API: GET /rest/api/3/field returns all fields with their IDs.
Common ones: Story Points = customfield_10016, Epic Link = customfield_10014, Sprint = customfield_10020.

Common errors

401 Basic auth failed

Cause

Wrong email or API token. On Jira Cloud, email is your Atlassian account email. Password is the API token, not your Atlassian password.

Fix

Regenerate a new API token at id.atlassian.com → Security → API tokens.

403 The caller does not have permission

Cause

Your account doesn't have access to the project or specific operation.

Fix

Ask a Jira admin to grant you project access. For Server: check your project role and global permissions.

404 Issue does not exist or you do not have permission

Cause

Issue key is wrong, or your account can't see the project.

Fix

Verify the issue key. Check you have Browse Projects permission for that project.

400 Field 'X' cannot be set

Cause

The field is not on the create/edit screen for that issue type, or it's a read-only field.

Fix

Ask admin to add the field to the screen. Or remove that field from your request.

400 Invalid JQL

Cause

Syntax error in the JQL string — often unquoted values or wrong operator.

Fix

Validate JQL in Jira's issue search UI first. Quote string values (status = "In Progress", not status = In Progress).

400 Transition is not valid

Cause

The transition ID doesn't exist for this issue, or the issue is already in the target status.

Fix

Use jira.issue.transitions to list valid transitions for the specific issue.

429 Rate limit exceeded

Cause

Jira Cloud rate limits REST API calls per user per minute.

Fix

Add delays between bulk operations. Use JQL with maxResults to batch fetches. Jira Cloud limit: ~10 req/sec per user.

XSRF check failed

Cause

Attempting to use cookie-based auth instead of Basic/Bearer token.

Fix

Ensure Conductor is using the API token, not a session cookie. Set the correct auth type in config.

Jira Cloud vs Server differences

Feature	Cloud	Server / DC
Auth	Email + API token	PAT or Basic (user/pass)
API version	REST API v3	REST API v2
User ID	accountId (UUID)	Username or name field
Rate limiting	~10 req/sec per user	No hard limit (server capacity)
Base URL	*.atlassian.net	Your internal hostname
Sprint field	customfield_10020	May differ — check /rest/api/2/field

All integrations