Skip to content

Tracker: Jira

Use this when your tickets live in Jira issues. The example here is the fictional TodoList product on acme.atlassian.net, in the Jira project TL.

The whole config

# yaml-language-server: $schema=https://raw.githubusercontent.com/holgerleichsenring/agent-smith/main/config/agentsmith.schema.json

agents:
  default-claude:
    type: claude
    models:
      scout:   { model: claude-haiku-4-5-20251001 }
      primary: { model: claude-sonnet-4-6 }
      planning:      { model: claude-sonnet-4-6 }
      summarization: { model: claude-haiku-4-5-20251001 }

repos:
  todolist-api:
    type: github
    url: https://github.com/acme-org/todolist-api
    auth: github_token
  todolist-worker:
    type: github
    url: https://github.com/acme-org/todolist-worker
    auth: github_token
  todolist-web:
    type: github
    url: https://github.com/acme-org/todolist-web
    auth: github_token

trackers:
  acme-jira:
    type: jira
    url: https://acme.atlassian.net
    project: TL
    auth: jira_token
    auth_email: agent-smith@acme.org    # Jira API needs email + token
    open_states: [Open, In Progress, To Do]
    done_status: Done
    close_transition_name: Done        # the transition Jira calls to reach done_status
    label_mode: true                   # Jira tags ≡ labels; see lifecycle labels below
    polling:
      enabled: false                   # use the webhook path; see Trigger it

projects:
  jira-todolist:
    agent: default-claude
    tracker: acme-jira
    repos: [todolist-api, todolist-worker, todolist-web]
    jira_trigger:
      project_resolution:
        strategy: tag
        value: todolist                # Jira labels are lowercase
      trigger_statuses: [Open, In Progress, To Do]
      done_status: Done
      pipeline_from_label:
        agent-smith-init:               init-project
        agent-smith-bug:                fix-bug
        agent-smith-feature:            add-feature
        agent-smith-security-scan:      security-scan

skills:
  source: default
  version: v3.0.1
  cache_dir: /var/lib/agentsmith/skills

secrets:
  claude_api_key: ${ANTHROPIC_API_KEY}
  github_token:   ${GITHUB_TOKEN}
  jira_token:     ${JIRA_API_TOKEN}

Jira-specific things to notice:

  • auth_email — Jira's REST API authenticates with an email plus an API token, not a token alone. The email is the account the agent acts as (you'll see it in the issue history).
  • close_transition_name — Jira doesn't expose a "set status" API. You move an issue between statuses by transitioning it, and transitions have names defined per project workflow. Set this to the transition that lands on your done_status. If you don't know it, look at the workflow diagram in Jira Settings → Issue Types → Workflows.
  • label_mode: true — colons aren't allowed in Jira labels, so the framework lifecycle labels use dashes (agent-smith-bug instead of agent-smith:bug).
  • polling.enabled: false — Atlassian Cloud webhooks are reliable; use them. Polling is the fallback for Jira Server / Data Center behind a firewall.

Authentication

Create an API token at id.atlassian.com/manage-profile/security/api-tokens. Set in the environment:

export JIRA_API_TOKEN=...

The token is scoped to the account that owns it. Make sure that account has permission to comment, transition, and label-edit issues in the project.

How tickets reach Agent Smith

  • Webhook (preferred). Jira Cloud posts to Agent Smith on issue updates. Set up in Webhooks: Jira.
  • Polling. For Jira Server / Data Center behind a firewall. Set polling.enabled: true and interval_seconds: 60 (or more — Jira's API rate limits get strict).
  • Manual CLI. agent-smith fix "TL-54 in jira-todolist" — note the project-prefixed issue key, that's Jira's native shape.

What gets written back to the ticket

When a run finishes:

  • Issue transitions via close_transition_name to done_status.
  • A new comment with the PR URLs and the run id.
  • The agent-smith-done label gets added; agent-smith-in-progress removed.

The label-mode flag determines the lifecycle label format (agent-smith-done vs agent-smith:done). Jira shops always set it to true.

Next