Jira Integration

Connect ElasticClaw to Jira Cloud to start workflow agents when issues move into a configured status.

How it works

A Jira workflow watches issue update events for a project, status, label, and assignee filter. When a matching issue moves into the trigger status, ElasticClaw creates an agent, writes Jira issue context intoCONTEXT.md, and injects the issue into the workflow stage.

  • Read the issue key, title, description, labels, project, status, and assignee
  • Require labels and suppress automation with exclude_labels
  • Move the issue to a working status when the agent starts
  • Move the issue through later workflow stages with move_issue
  • Use polling as a fallback for missed webhook deliveries

1. Create a Jira API token

  1. Go to Atlassian account settings - Security - API tokens
  2. Create a token named ElasticClaw
  3. Copy the token and store it with your ElasticClaw Server secrets
bash
export JIRA_BASE_URL=https://your-site.atlassian.net
export JIRA_USERNAME=you@example.com
export JIRA_API_TOKEN=ATATT3x...

Jira Cloud basic auth uses your Atlassian account email address as the username and the API token as the password.

2. Configure the workspace issue tracker

text
Settings -> Workspaces -> my-app -> Issue Trackers
Add Jira:
  workspace: default
  base URL: https://your-site.atlassian.net
  username: you@example.com
  token: ${JIRA_API_TOKEN}
  webhook secret: ${JIRA_WEBHOOK_SECRET}
The Jira account must be able to browse the project, read issues, create comments, edit labels, transition issues, and delete issues if your tests or cleanup scripts create temporary issues.

3. Configure a Jira webhook

Add a Jira webhook that sends issue update events to ElasticClaw Server. The workspace-scoped URL is preferred when the webhook belongs to one ElasticClaw workspace.

  • URL: https://server.example.com/api/workspaces/my-app/webhooks/jira
  • Events: Issue updated
  • Secret header: X-ElasticClaw-Webhook-Secret: ${JIRA_WEBHOOK_SECRET}

If one Jira webhook should fan out across all configured ElasticClaw workspaces, use https://server.example.com/api/integrations/jira/webhook. ElasticClaw will resolve matching Jira workflows globally.

Jira Cloud webhook management is limited for personal API tokens. If your Jira plan or app setup cannot add the custom secret header, leave the workspace tracker webhook secret empty and restrict the endpoint at the network layer.

4. Create a workflow

Jira workflows use trigger.jira. Project filters use the Jira project key, such as KAN in KAN-123.

yaml
# .elasticclaw/workflows/jira-bugfix.yaml
schema_version: v1
name: jira-bugfix

trigger:
  jira:
    event: status_changed
    workspace: default
    projects:
      - KAN
    states:
      - "Ready for Agent"
    labels:
      - elasticclaw
    exclude_labels:
      - blocked

concurrency_group: jira-bugfix
working_status: "Agent Working"

stages:
  - id: working
    label: Working
    entry: true
    on_enter:
      inject: |
        Issue: {{.Issue.Identifier}} - {{.Issue.Title}}
        URL: {{.Issue.URL}}

        Read CONTEXT.md and start working.

  - id: pr_opened
    label: PR Opened
    triggers:
      - message_contains: "[DONE]"
    on_enter:
      move_issue: "In Review"

  - id: merged
    label: Merged
    triggers:
      - pr_merged: {}
    on_enter:
      move_issue: Done
    terminal: true

working_status moves the Jira issue as soon as the agent starts. Later stages can move the same issue with move_issue.

Label filters

Jira triggers require every configured labels value and reject issues that have any configured exclude_labels value. The same filters apply to webhook delivery and the polling fallback path.

yaml
trigger:
  jira:
    projects: [KAN]
    states: ["Ready for Agent"]
    labels: [elasticclaw]
    exclude_labels: [blocked, do-not-automate]

5. Push the workflow

bash
elasticclaw workspace push my-app
elasticclaw workflow push --workspace my-app .elasticclaw/workflows/jira-bugfix.yaml

Template variables

In stages[].on_enter.inject, automatic Jira workflows expose this issue object:

{{.Issue.Identifier}} — Jira issue key, such as KAN-123.

{{.Issue.Title}} — Jira issue summary.

{{.Issue.URL}} — Browser URL for the issue.

{{.Issue.Description}} — Jira issue description.

Polling fallback

ElasticClaw also polls Jira for recently updated matching issues. The polling path uses the same project, status, label, and assignee filters as webhooks, and claw creation is deduplicated so a webhook and poll for the same issue do not create two agents.

Jira status names and transition names are workspace-specific. Use exact names from your Jira workflow for states, working_status, and move_issue.