Skip to main content

Jira Integration

Connect Jira to sync work items, epics, and project data between Clears AI and your Jira workspace.

note

Integration settings are only visible to users with the Admin role. Regular users cannot access or modify integration configuration.

Choosing how to connect​

There are two supported ways to connect Jira. Both are fully supported:

  • Connecting with the Clears app - install the Clears app on your Atlassian site. Clears then acts as its own app user, and no webhook is needed. Available to new accounts. Accounts already connected through OAuth are moved to the Clears app with Clears' help.
  • Connecting via OAuth - authorize Clears AI with the OAuth popup and configure a webhook yourself. Accounts connected this way keep using it, fully supported, until they move to the Clears app.

If you don't see Install Clears for Jira & Confluence in Settings → Integrations → Jira, your account uses OAuth; the instructions below still apply.

Connecting with the Clears app​

Installing the Clears app connects Jira and Confluence together. There is nothing to copy and no webhook to set up.

Before you start​

You must be an Atlassian site admin to install the app. This is an Atlassian rule for apps that have their own identity. Unlike the OAuth flow, a regular Jira user cannot install it. You also need the Admin role in Clears to confirm the connection.

The three steps​

  1. In Clears: go to Settings → Integrations → Jira and click Install Clears for Jira & Confluence. Atlassian's install page opens in a new tab, showing the app "By Clears" with its permissions, privacy and support links. Choose your site, tick Jira and Confluence together, and install.
  2. In Jira: open the app's Get started page and click Connect to Clears. Click Get started on Atlassian's post-install screen if it shows one. Otherwise go to Jira Settings (⚙) → Apps → Manage apps → Clears → Get started. Clears opens in a new tab.
  3. In Clears: a screen asks Connect <site> to your Clears account? Check the site name, then click Confirm.

Atlassian's yellow banner​

The install dialog always shows a yellow banner:

Only install apps from developers you trust. Before you install this app on your Atlassian site, please review app permissions and vendor details.

Atlassian shows this for every app installed from outside the Atlassian Marketplace, and the app cannot remove it. It is expected. Review the permissions and vendor details, then continue.

Confirming the site​

The confirm screen shows the Atlassian site and your Clears account name. Check that the site is the one you mean to connect before clicking Confirm. Confirming binds that site to your Clears account. If you did not start this from Jira yourself, click Cancel.

If the link has expired (it lasts 10 minutes), was already used, or isn't recognised, open Get started in Jira again and click Connect to Clears. If the screen says the account or site is already connected elsewhere, uninstall the app there or contact support.

Once connected, Settings → Integrations → Jira shows the site, the products covered with their install dates, and Acting as: Clears app.

What shows as Clears and what shows as a person​

In JiraShown as
Tasks Clears creates (reporter)Clears
Tasks a user creates (reporter)That user
Comments made from ClearsClears
Status changes made from ClearsClears

Projects Clears cannot access​

If Clears lists projects it cannot access, the project's permission scheme has removed the atlassian-addons-project-access role. Add that role back to the permission scheme under Project settings → Permissions, and Clears can reach the project again.

Confluence​

One install covers both products. When you tick Jira and Confluence in the install dialog, Confluence is connected at the same time, and Settings → Integrations → Confluence shows the same site and install dates. You don't connect Confluence separately.

Uninstalling​

Uninstall the app from your Atlassian site: Jira Settings (⚙) → Apps → Manage apps, find Clears, and remove it. This is done in Atlassian, not in Clears.

Existing OAuth connections​

If your account already has an OAuth connection, it keeps working as before: Settings shows it with its status and Disconnect. Clears moves existing OAuth accounts to the Clears app together with you. Once your account uses the Clears app, the webhook controls are hidden because they are not needed.

Connecting via OAuth​

This path remains fully supported.

  1. Navigate to Settings → Integrations → Jira
  2. Click Connect Jira
  3. A popup window opens to Jira's OAuth authorization screen
  4. Grant Clears AI access to your Jira workspace
  5. The popup closes and the connection status updates to active

Jira integration settings

Once connected, you'll see your workspace name and a Last connected timestamp.

Testing the Connection​

Click Test Connection to verify that Clears AI can communicate with your Jira instance. A success or error notification appears confirming the result.

Webhook Configuration​

After connecting, a webhook section displays:

  • Webhook URL - the endpoint Jira sends events to (with a copy button for convenience)
  • Webhook Secret - used to verify incoming webhook payloads; click Edit to update

Configure this webhook in your Jira workspace to enable real-time event synchronization.

Syncing Data​

Click Sync Epics to pull the latest epic and project data from Jira into Clears AI. This is useful after making changes in Jira that you want reflected immediately.

Project Status Audit​

The Jira Project Statuses section helps ensure your Jira projects have the status configurations required by Clears AI's story lifecycle.

  1. Select one or more projects from the dropdown
  2. Click Audit to analyze the status configuration
  3. The audit identifies any missing statuses or transitions that the AI workflow requires
  4. Click Auto-fix to automatically create the missing statuses and transitions in Jira

This is important when first connecting a Jira project - the workflow expects specific status transitions (e.g., To Do → Enriched → In Progress → Validation → Done), and the audit ensures your Jira project supports them.

Field and Status Mappings​

  • Field Mappings - map Jira custom fields to Clears AI fields, ensuring data flows correctly between systems
  • Status Mappings - map Jira status names to Clears AI's internal status values

Disconnecting​

Click Disconnect to revoke the OAuth connection. This stops all synchronization between Clears AI and Jira.