# Jira URL: https://docs.clearly-ai.com/docs/integrations/issue-trackers/jira Description: Connect Clearly AI to Jira. Connect Jira so Clearly AI can read issue data and attachments, create or update Jira issues, add comments, and receive Jira events for Workflows. Clearly AI acts as the Jira user whose credentials you configure. For example, if the API token belongs to `alex@example.com`, comments created by Clearly AI appear as Alex. [Image: Jira comment authored by the credential owner] ## Prerequisites [#prerequisites] * A Clearly AI account with access to **Integrations**. * A Jira Cloud site, such as `https://mycompany.atlassian.net`. * Permission to create a Jira API token. * A Jira account with access to the projects and issues Clearly AI should use. For shared or production use, ask your IT team to create a dedicated Jira service account, such as **Clearly AI bot**, and generate the API token from that account. This keeps Clearly AI activity separate from individual employee accounts. ## Make the Jira account email visible [#make-the-jira-account-email-visible] Jira webhook handling requires the email address for the credential owner to be visible. In Atlassian account settings, open [Profile and visibility](https://id.atlassian.com/manage-profile/profile-and-visibility) and set the account email visibility to **Anyone**. [Image: Atlassian profile visibility settings] ## Create the Jira API token [#create-the-jira-api-token] 1. Open [Atlassian account security](https://id.atlassian.com/manage-profile/security). 2. Under **API tokens**, click **Create and manage API tokens**. 3. Create an API token with the scopes below. 4. Set an expiry that matches your security policy. Atlassian tokens can expire no later than one year after creation. 5. Copy the token. You will paste it into Clearly AI in the next step. Use these scopes: | Scope | Purpose | | -------------------------------- | ----------------------------------------------- | | `delete:issue:jira` | Delete issues during cleanup | | `read:application-role:jira` | Read the authenticated user's application roles | | `read:attachment:jira` | Read and download issue attachments | | `read:avatar:jira` | Read user avatars | | `read:comment.property:jira` | Read comment metadata | | `read:comment:jira` | Read issue comments | | `read:field-configuration:jira` | Read field configurations | | `read:field.default-value:jira` | Read default field values | | `read:field.option:jira` | Read allowed field values | | `read:field:jira` | Read Jira field definitions | | `read:group:jira` | Read the user's Jira groups | | `read:issue-details:jira` | Read issue details | | `read:issue-meta:jira` | Read issue field metadata | | `read:issue-security-level:jira` | Read issue security levels | | `read:issue-status:jira` | Read issue statuses | | `read:issue-type-hierarchy:jira` | Read parent and child issue relationships | | `read:issue-type:jira` | List project issue types | | `read:issue.changelog:jira` | Read issue change history | | `read:issue.remote-link:jira` | Read issue remote links | | `read:issue.transition:jira` | Read available issue transitions | | `read:issue.vote:jira` | Read issue votes | | `read:issue:jira` | Read and search issues | | `read:priority:jira` | List Jira priorities | | `read:project-category:jira` | Read project categories | | `read:project-role:jira` | Read project roles | | `read:project-version:jira` | Read project versions | | `read:project.component:jira` | Read project components | | `read:project.property:jira` | Read project properties | | `read:project:jira` | List projects | | `read:status:jira` | List project workflow statuses | | `read:user.property:jira` | Read Jira user details | | `read:user:jira` | Read Jira users | | `write:attachment:jira` | Upload issue attachments | | `write:comment.property:jira` | Write comment metadata | | `write:comment:jira` | Add issue comments | | `write:issue.property:jira` | Write issue properties | | `write:issue.remote-link:jira` | Add issue remote links | | `write:issue:jira` | Create and update issues | Include every scope in this table when you create a granular API token. Jira Forms only accepts the classic `read:jira-work` scope, so a granular token fetches issues without their forms. [Image: Jira API token scope selection] [Image: Jira API token created] ## Connect Jira in Clearly AI [#connect-jira-in-clearly-ai] 1. In Clearly AI, open **Organization settings**, select **Integrations**, then click **Set up** on the Jira card. 2. Under **Authentication**, select **Shared API Token**. 3. In **Base URL**, enter your Jira site URL, such as `https://mycompany.atlassian.net`. 4. In **User Email**, enter the email address for the Jira account that owns the API token. 5. In **Shared API Token**, paste the API token. 6. Check **I understand** under the shared-credential notice, then click **Add workspace credential**. Clearly AI tests the credential and enables the integration only when the test passes. If the test fails, check the token's scopes, the email address, and the account's access to the Jira site. ## Create Jira issues from Chat [#create-jira-issues-from-chat] Chat can create Jira issues through the workspace Jira connector. With the default **Ask** permission on Jira's write tools, Chat requests approval before creating an issue, and the approval preview lists the issue fields, including **Parent epic** when set. Before creating an issue, Chat asks whether it should go under an epic unless you already specified one or said you want no epic. Give Chat the epic key, such as `SEC-123`, or its title. If you give a title, Chat searches Jira for the key. Say you want no epic to create a top-level issue. Jira decides whether the parent is valid for the issue type. ## Configure Jira webhooks for Workflows [#configure-jira-webhooks-for-workflows] Configure a webhook if you want Jira events, such as issue updates or label changes, to trigger Clearly AI Workflows. ### Generate the Clearly AI webhook secret [#generate-the-clearly-ai-webhook-secret] 1. In Clearly AI, open **Organization settings**, select **Integrations**, click **Configure** on the Jira card, open the **Webhooks** tab, and click **Edit webhook**. 2. Click **Generate new secret** next to **Secret**. Copy the secret and store it temporarily. 3. Click **Apply and Test**. 4. Click **Edit webhook** again and copy the **Webhook URL**. You will use both the webhook URL and the secret in Jira automation. ### Create a Jira automation rule [#create-a-jira-automation-rule] In Jira, open **Project settings > Automation > Create rule > Create from scratch**. Use Jira **Automation**, not Jira **Webhooks**. The example below sends an event to Clearly AI when selected labels are added or changed. 1. Add a trigger: * Select **Field value changed**. * Set the field to **Labels**. * Set the change type to **Any changes to the field value**. 2. Add a condition: * Select **Work item fields condition**. * Set the field to **Labels**. * Set the condition to **contains any of**. * Choose the label values that should trigger Clearly AI, such as `clearly-needs-review`. 3. Add an action: * Select **Send web request**. * Set **Web Request URL** to the Clearly AI **Webhook URL**. * Set **HTTP Method** to **POST**. * Set **Web Request Body** to **Issue Data (Automation format)**. * Add the headers below. * Enable **Check to allow other rule actions to trigger this rule** if another automation may add the trigger label. | Header | Value | | -------------------------- | ------------------------------------------------------------------------------------- | | `X-Clearly-Webhook-Secret` | The **Webhook Secret** from Clearly AI | | `X-Clearly-User` | The Clearly AI user email to use when Jira cannot resolve a valid user from the event | [Image: Jira automation web request configuration] ## Validate the webhook [#validate-the-webhook] Return to the Jira integration in Clearly AI and use **Validate your request configuration**. A correct setup returns `200 OK`. After validation succeeds, Jira events that match your automation rule can trigger Clearly AI Workflows. [Image: Clearly AI webhook validation result] ## FAQs [#faqs] Chat uses the connector's tool list from its last sync. If the Jira connector's tools were last synced before 2.10.10, an admin must open **Customize** > **Manage** tab > **Manage** on Jira > **Sync tools**. Syncing adds new tools and keeps existing tool permissions. Confirm the API token is active, the email matches the token owner, and the token includes the required scopes. Clearly AI comments as the Jira account that owns the API token. Use a dedicated service account if you need consistent attribution. Confirm the Jira automation sends **Issue Data (Automation format)**, includes both required headers, and uses the current Clearly AI webhook URL and secret. Confirm the Jira automation rule is enabled, the issue update matches your trigger and condition, and the Workflow is enabled in Clearly AI.