Skip to main content
The Jira integration lets your agents work with Jira Cloud issues: search with JQL, read issue details and history, create and update issues, comment, change status, and move files between Jira and the agent’s sandbox. Agents can also raise Jira Service Management (JSM) Ops alerts, and Jira events can start agent runs through triggers.

Features

Issue Management

Create, update, comment on, and transition issues, including projects that require custom fields.

Search and History

Search issues with JQL and read an issue’s comments, change history, and available transitions.

Attachments

Attach files from the agent’s sandbox to an issue, or download an issue’s attachments into the sandbox for analysis.

Triggers

Run an agent, or create a Cotool alert, from Jira webhooks or Jira Automation rules.

Connect Jira

Go to Integrations in the Cotool sidebar, open Jira, and click Connect. Choose one of two connection methods.

Connect with OAuth

The fastest setup. Select Connect with OAuth, then authorize Cotool in Atlassian. The connection uses the authorizing user’s Jira access, and it stops working if that user is later deactivated.

Use a service account

A service account is a non-human Atlassian identity, so the connection survives employee offboarding. It requires Atlassian centralized user management.
1

Create a service account

In Atlassian administration, create a service account.
2

Grant Jira product access

Give the service account Jira product access (an application role such as Jira Software). Project-level permissions alone are not enough: Jira rejects writes from an account without product access.
3

Add it to your projects

Add the service account to the relevant projects with a role that allows the actions your agents need.
4

Create an OAuth 2.0 credential

Create an OAuth 2.0 credential for the service account with these scopes, and copy its client ID and client secret:
  • read:jira-work
  • write:jira-work
  • read:jira-user
  • read:ops-alert:jira-service-management
  • write:ops-alert:jira-service-management
5

Find your Jira Cloud ID

Open https://<your-site>.atlassian.net/_edge/tenant_info and copy the cloud ID.
6

Save the service account in Cotool

In the Jira connect dialog, select Use a service account, enter the Client ID, Client secret, and Jira Cloud ID, and click Save service account.
You can switch methods later from the same dialog. Completing the OAuth flow replaces a saved service account, and the saved client secret is removed.

Available Tools

When an agent has the Jira integration enabled, it can use these tools:
Projects can require extra fields, such as a custom severity field, a due date, or a parent for sub-tasks. Agents call jira_getCreateFieldMetadata to learn the required fields before creating an issue in those projects.

Triggers

Jira events can start a response agent. On the agent’s page, add a trigger and choose one of two Jira sources. Both create a Cotool alert for each event by default. Turn off Create alert to run the agent directly instead. See Triggering Agents for how triggers work.

Jira webhooks

Uses Jira’s native webhooks, with payloads signed by a secret Cotool generates. This trigger requires a connected Jira integration and Jira admin access to create the webhook.
1

Add a Jira trigger

Add a trigger and select Jira. Cotool shows a webhook URL and a webhook secret.
2

Create the webhook in Jira

Click Open Jira webhook settings, or go to Settings > System > Webhooks in Jira, and select Create webhook. Enter a name, paste the webhook URL, choose the events and filters to trigger on, and use the webhook secret from Cotool. Save the webhook.
3

Save the trigger

Back in Cotool, click Save webhook.

Jira Automation

Uses a Jira Automation rule’s Send web request action, so it does not need Jira admin access to native webhooks.
1

Add a Jira Automation trigger

Add a trigger and select Jira Automation. Cotool shows a webhook URL and a token.
2

Configure the rule in Jira

In your Jira Automation rule, add a Send web request action that sends a POST request to the webhook URL. Add an X-Webhook-Auth header set to the token from Cotool. Put the issue details the agent needs in the request body, for example {"issue": "{{issue.key}}", "summary": "{{issue.summary}}"}.
3

Save the trigger

Back in Cotool, click Save Jira Automation trigger.

Troubleshooting

  • JSM alert creation fails with an authorization error. Connections made before JSM Ops alerts were supported lack the alert scopes. Click Reauth on the Jira integration page, select Connect with OAuth, and complete the Atlassian consent again. For a service account, add the two ops-alert scopes to its OAuth 2.0 credential.
  • A service account can read issues but writes fail. Grant the service account Jira product access, not only project permissions.
  • Creating an issue fails because a field is missing or invalid. The project requires additional fields. Ask the agent to check the project’s create fields with jira_getCreateFieldMetadata and set them.