> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to Jira

> Connect Overcut to Jira so agents can read, create, and update issues directly from your workflows.

Connect Overcut to Jira so agents can discover your projects and work with issues
directly. Once connected, agents can read, create, transition, comment on, and
link issues as part of your workflows.

This page covers the concepts that apply to every Jira connection. **The exact
setup steps depend on where Overcut runs and where your Jira lives** - pick your
path in [Which setup do I need?](#which-setup-do-i-need) below.

## What You Can Do

With Jira connected, Overcut agents can:

* **View Projects**: See all Jira projects the connected account has access to
* **Create Issues**: Create new tickets with descriptions, assignees, and labels
* **Update Issues**: Modify existing tickets and change their status
* **Add Comments**: Leave comments on issues with rich text formatting
* **Track Changes**: Receive webhook events when issues are created or updated
* **Search Issues**: Find specific tickets using JQL queries
* **Link Issues**: Create, remove, and read typed relationships between issues

## Which setup do I need?

Two questions decide your path: **where Overcut runs** and **where your Jira
lives**.

| Where Overcut runs      | Where your Jira lives               | Follow this guide                                                                |
| ----------------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
| Overcut Cloud (managed) | Jira Cloud (`*.atlassian.net`)      | [Jira Cloud on Overcut Cloud (Forge app)](/docs/integrations/jira/cloud)         |
| Self-hosted Overcut     | Jira Cloud (`*.atlassian.net`)      | [Jira Cloud from self-hosted Overcut](/docs/integrations/jira/cloud-self-hosted) |
| Self-hosted Overcut     | Jira Server / Data Center (on-prem) | [Jira Server / Data Center](/docs/integrations/jira/data-center)                 |

<Note>
  Overcut Cloud connects to **Jira Cloud only** (the managed Forge app is
  Cloud-only). On-prem **Jira Server / Data Center** can only be connected from a
  **self-hosted Overcut** deployment, using your own OAuth credentials on your
  instance.
</Note>

<CardGroup cols={3}>
  <Card title="Jira Cloud on Overcut Cloud" icon="cloud" href="/docs/integrations/jira/cloud">
    Managed Overcut + Jira Cloud. Install the Overcut Forge app. No credentials
    to manage.
  </Card>

  <Card title="Jira Cloud, self-hosted Overcut" icon="server" href="/docs/integrations/jira/cloud-self-hosted">
    Self-hosted Overcut + Jira Cloud. Connect directly with your own Atlassian
    OAuth app (3LO or 2LO).
  </Card>

  <Card title="Jira Server / Data Center" icon="building" href="/docs/integrations/jira/data-center">
    Self-hosted Overcut + on-prem Jira. Connect with an OAuth application link on
    your instance.
  </Card>
</CardGroup>

## Using Jira in Your Workflows

Once connected, Jira projects appear as available sources when you:

* Add a **Source** to a workflow
* Configure a **Trigger** that monitors projects
* Set up **Actions** that work with tickets

### Example Workflows

* **Bug Triage**: Automatically create Jira tickets when bugs are detected in code
* **Feature Requests**: Convert GitHub issues to Jira tickets for project tracking
* **Status Updates**: Keep Jira tickets updated with latest development progress
* **Release Management**: Track all issues related to a specific release

<Note>
  For workflows that need to automatically identify which code repositories are most relevant to Jira tickets, consider using the <code>repo.identify</code> action. This action uses AI-powered analysis and repository correlations to determine the best repositories to work with for each ticket. Learn more in our <a href="/docs/repositories/repository-mapping">Repository Mapping guide</a>.
</Note>

## Working with Issues

### Creating Tickets

Agents can create new Jira issues with:

* Summary and description
* Assignee (if specified)
* Labels and priority
* Project and issue type

### Updating Tickets

Agents can modify existing issues by:

* Updating fields like summary or description
* Changing assignees or labels
* Transitioning between statuses (e.g., "In Progress" to "Done")
* Adding comments with context

### Finding Issues

Search for specific tickets using:

* Project key (e.g., "PROJ-123")
* JQL queries for complex searches
* Status filters (open, closed, in progress)
* Assignee or label filters

## Provider-Specific Behaviors

* **Status names**: Issue trigger filters (such as **Status From** and **Status To**) use the exact status labels from your Jira project workflow. Use the values shown on the issue or in the project workflow editor, including capitalization and spacing. Jira treats `Done` and `Closed` as distinct statuses even if they share the same status category.
* **Linked issues**: Agents can create, remove, and read typed issue links in Jira. Jira uses directional relationship labels such as `blocks` and `is blocked by`, defined in your workspace (agents can inspect the available types before linking). Cross-project linking works when Jira allows it. See the [tools reference](/docs/reference/tools) for how linked relationships work across providers.

## Permissions

In every setup, Overcut needs read and write access to projects, issues, and
comments. **The exact scopes you grant differ by path** (Jira Cloud uses granular
Atlassian scopes; Jira Server / Data Center uses a coarse instance-level scope),
so they are listed on each connection guide:

* [Jira Cloud on Overcut Cloud (Forge app)](/docs/integrations/jira/cloud)
* [Jira Cloud from self-hosted Overcut](/docs/integrations/jira/cloud-self-hosted)
* [Jira Server / Data Center](/docs/integrations/jira/data-center)

In all cases, the **account you authorize with owns every issue, comment, and
transition** Overcut performs, so authorize as a dedicated service account (for
example `overcut-bot`), not your personal admin account.

## Troubleshooting

General issues are covered below. For path-specific problems (callback URL
mismatches, webhook setup, service-account access), see the troubleshooting
section on your connection guide.

### Connection Issues

* Ensure the connected account has admin permissions in your Jira workspace
* Try disconnecting and reconnecting the integration
* Check that your Jira instance is accessible

### Permission Errors

* Verify the connected app or account has the necessary permissions in Jira
* Check that you're trying to access projects the account has access to
* Ensure the Jira user account has appropriate project permissions

### Missing Projects

* The integration only shows projects the connected account has access to
* Check your Jira user permissions for specific projects
* Verify the project keys are correctly configured

## Getting Help

If you encounter issues with the Jira integration:

1. Check the troubleshooting section on your connection guide
2. Review your Jira permissions and project access
3. Contact Overcut support with specific error messages
4. Ensure your Jira instance is running and accessible