Jira

Jira integration lets you delegate work from your Jira board to Errand’s AI agents. When a Jira issue matches your configured filters (issue type, label, project), Errand automatically creates a task, executes it, and posts the results back to the Jira issue as comments, status transitions, and label updates.

Features

• Webhook triggers — automatically create tasks when Jira issues are created or updated
• Configurable filters — match on event type, issue type, labels, and project key
• Completion actions — comment results, transition status, assign issues, add labels
• Atlassian MCP tools — give agents the ability to read and interact with Jira during task execution
• Bidirectional tracking — Errand tracks the link between tasks and Jira issues for deduplication and callbacks

Prerequisites

• A Jira Cloud instance (Jira Server/Data Center is not supported)
• A service account with an API token scoped to your Jira instance
• A way for Jira to reach your Errand installation:
  • Errand Cloud (recommended) — the Cloud Service relays Jira webhooks to your local installation
  • Self-managed — expose your Errand server to the internet so Jira can deliver webhooks directly

Overview

Setup has three parts:

1. Connect Jira credentials — so Errand can call the Jira API for completion actions
2. Create a webhook trigger — configure which Jira events create tasks and what happens on completion
3. Register the webhook in Jira — point Jira at your Errand webhook URL

Optionally, you can also add the Atlassian MCP server to a task profile so that agents can interact with Jira issues during execution.

---

Step 1: Create a Jira API Token

1. Log in to id.atlassian.com with the account you want to use as the service account
2. Go to Security > API tokens
3. Click Create API token
4. Give it a label (e.g. “Errand”) and click Create
5. Copy the token — you won’t be able to see it again

Service account

Use a dedicated service account (e.g. errand-bot@yourcompany.com) rather than a personal account. This keeps the audit trail clean and lets you scope permissions appropriately.

Step 2: Find Your Cloud ID

Your Atlassian Cloud ID identifies your Jira instance. To find it:

1. Go to your Jira instance (e.g. https://yourcompany.atlassian.net)
2. Navigate to https://yourcompany.atlassian.net/_edge/tenant_info
3. Copy the cloudId value from the JSON response

Step 3: Connect Jira in Errand

1. Open the Errand UI and go to Settings > Integrations
2. Find the Jira card and click Connect Jira
3. Fill in:
   • Site URL — your Jira instance URL (e.g. https://yourcompany.atlassian.net)
   • Cloud ID — from Step 2
   • API Token — from Step 1
   • Service Account Email — the email address of the account that owns the API token
4. Click Save & Verify

Errand verifies the token by calling the Jira API. If verification succeeds, the card shows “Connected” with the account display name.

Step 4: Create a Webhook Trigger

1. Go to Settings > Task Generators
2. In the Webhook Triggers section, click Add Trigger
3. Configure the trigger:

Source and Name

• Source — select “Jira”
• Name — a descriptive name (e.g. “Jira Bug Triage”, “Story Analysis”)

Task Profile

Select which task profile the agent should use when executing tasks from this trigger. The profile controls the model, system prompt, MCP tools, and skills available to the agent.

Filters

Filters determine which Jira events create tasks. All filters are ANDed together — an event must match every configured filter. Leave a filter empty to match all values.

Filter	Description	Example
Event Types	Which Jira events to react to	jira:issue_created, jira:issue_updated
Issue Types	Which issue types to match	Story, Bug, Task, Feature, Epic
Labels	Trigger when an issue has this label	errand, ai-review
Projects	Which Jira project keys to scope to	SCRUM, WEBAPP

Label filter behavior

For jira:issue_created events, the label must be present on the issue at creation time. For jira:issue_updated events, the filter matches if the label is currently on the issue — it doesn’t need to have been added in that specific update.

Completion Actions

Configure what Errand does when a task finishes:

Action	Description
Assign to service account	Claims the Jira issue when the task starts
Add comment with task reference	Posts a comment when the task starts and when it finishes
Comment output on complete	Includes the full task output in the completion comment
Add label on complete	Adds a label to the issue (e.g. errand-done)
Transition on complete	Moves the issue to a target status (e.g. Done)

Webhook Secret

Click Generate to create a cryptographic secret, or paste your own. This secret is used for HMAC-SHA256 signature verification — Jira signs each webhook payload with it, and Errand verifies the signature before processing.

The secret is stored encrypted and never shown again after the initial save. If you need to change it, generate a new one and update the webhook configuration in Jira.

4. Click Save

Step 5: Register the Webhook in Jira

1. In Jira, go to Settings (gear icon) > System > WebHooks
2. Click Create a WebHook
3. Configure:
   • Name — e.g. “Errand”
   • Status — Enabled
   • URL — your Errand webhook URL:
     • Direct: https://your-errand-instance/webhooks/jira
     • Errand Cloud: the cloud relay URL shown on the trigger detail page in Errand
   • Secret — paste the webhook secret from Step 4
4. Under Events, select the events that match your trigger’s event type filters:
   • For jira:issue_created — check Issue > created
   • For jira:issue_updated — check Issue > updated
5. Optionally filter by JQL to limit which issues fire the webhook (e.g. project = SCRUM)
6. Click Create

Testing

Create a test issue in the matching project with the matching label and issue type. Check Errand’s task board — a new task should appear within a few seconds. If it doesn’t, check the server logs for filter rejection messages.

---

Optional: Add Atlassian MCP Server to Task Profiles

The webhook trigger handles inbound events and completion callbacks. If you also want the AI agent to read and interact with Jira issues during task execution (e.g. look up related issues, read comments, create sub-tasks), add the Atlassian MCP server to the task profile.

1. Go to Settings > Agent Configuration
2. Expand the MCP Server Configuration section
3. In the JSON text box, add the Atlassian MCP server. If the field is empty, paste this full configuration:

   {
     "mcpServers": {
       "atlassian": {
         "url": "https://mcp.atlassian.com/v1/mcp",
         "headers": {
           "Authorization": "Bearer ${JIRA_API_TOKEN}"
         }
       }
     }
   }

   If you already have other MCP servers configured, add the "atlassian" entry alongside them inside the existing "mcpServers" object.
4. Click Save

The ${JIRA_API_TOKEN} placeholder is automatically replaced with the API token from your Jira credentials (configured in Step 3) at task execution time. You don’t need to hardcode the token.

Note

The Atlassian MCP server is a hosted service provided by Atlassian. It gives AI agents tools to search issues, read issue details, create issues, add comments, and manage projects. See the Atlassian MCP documentation for the full list of available tools.

If you only want certain task profiles to have Jira access, add the MCP server to those specific profiles in Settings > Task Profiles rather than to the global agent configuration. The profile assigned to your webhook trigger controls which MCP servers are available during execution.

---

How It Works

When everything is connected, the flow is:

1. A Jira issue is created or updated, matching your trigger filters
2. Jira sends a webhook to Errand (directly or via Cloud relay)
3. Errand verifies the HMAC signature and identifies the matching trigger
4. Errand creates a task with the issue summary, description, and the trigger’s task profile
5. The AI agent executes the task using the configured model, tools, and skills
6. On completion, Errand posts results back to the Jira issue (comments, transitions, labels)

Each Jira issue creates at most one task — duplicate webhooks for the same issue are automatically deduplicated.

---

Troubleshooting

Issue	Solution
”Not Connected” on Jira card	Verify the Cloud ID, API token, and site URL in Settings > Integrations > Jira
Webhooks arrive but no tasks created	Check the trigger’s filters — the server log shows which filter rejected the event and why (event type, issue type, labels, project)
“Add Trigger” button is disabled	Jira credentials must be connected first — go to Settings > Integrations
Completion comments not appearing	Verify the API token has permission to comment on issues in the target project
Transition fails	The target status name must match an available transition exactly (case-insensitive). Check the issue’s current workflow for valid transitions
${JIRA_API_TOKEN} not replaced	Ensure Jira credentials are saved in Settings > Integrations > Jira — the placeholder is resolved from those stored credentials
Cloud relay returns 401	The webhook secret in Jira must match the secret configured on the trigger in Errand