> ## 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.

# Jira Server / Data Center

> Connect an on-prem Jira Server or Data Center instance to a self-hosted Overcut deployment using an OAuth application link.

Use this path when you run **Overcut on your own infrastructure** and your Jira is
**self-hosted Jira Server or Data Center** (an on-prem instance, not
`*.atlassian.net`). You connect with an **OAuth 2.0 incoming Application Link**
created on your Jira instance. Each deployment uses its own client credentials;
there is no shared Overcut Cloud client.

<Note>
  Not your setup? See [Which setup do I need?](/docs/integrations/jira#which-setup-do-i-need).
  For Atlassian-hosted Jira Cloud, use the [Forge app](/docs/integrations/jira/cloud)
  (Overcut Cloud) or [direct OAuth](/docs/integrations/jira/cloud-self-hosted)
  (self-hosted Overcut).
</Note>

## How it differs from Jira Cloud

|                 | Jira Server / Data Center                           | Jira Cloud                                            |
| --------------- | --------------------------------------------------- | ----------------------------------------------------- |
| OAuth endpoints | Your instance (`{instance}/rest/oauth2/latest/...`) | Atlassian-central (`auth.atlassian.com`)              |
| Authorization   | 3LO only (browser consent)                          | 3LO or 2LO                                            |
| Scope           | `WRITE` (coarse, instance-level)                    | `read:jira-work`, `write:jira-work`, `read:jira-user` |
| REST API        | v2 (`/rest/api/2`)                                  | v3 + ADF                                              |
| Webhook         | Manual paste                                        | Manual paste                                          |

## Prerequisites

* A **Jira Server or Data Center** instance reachable from your Overcut
  deployment over **HTTPS**
* **Administrator** access to that Jira instance (to create the Application Link
  and the webhook)
* A self-hosted Overcut deployment you operate (see [Deployment configuration](#deployment-configuration))

<Warning>
  The Jira account you authorize with **owns every issue, comment, and transition**
  Overcut performs. Authorize while signed in as a dedicated service account (for
  example `overcut-bot`), not your personal admin account. An incognito window is
  the safe way to avoid consenting as yourself. The service account must be a
  licensed Jira user with real access to the target projects.
</Warning>

## Connect

<Steps>
  <Step title="Create an OAuth 2.0 incoming Application Link in Jira">
    As a Jira administrator, go to **Administration (cog) -> Applications ->
    Application links** (on some versions this lives under **System -> OAuth**),
    and create an **incoming** OAuth 2.0 link.

    Set the **redirect / callback URL** to your deployment's Overcut callback,
    exactly:

    ```
    https://<your-overcut-domain>/jira-server-auth-app/callback
    ```

    This must match the `JIRA_SERVER_REDIRECT_URI` server setting character for
    character, and must use **https**.

    Grant the link the **`WRITE`** scope (Jira DC scopes are instance-level:
    `READ` / `WRITE` / `ADMIN`; `WRITE` covers issue and comment
    create / update / transition). Save, then copy the generated **Client ID** and
    **Client Secret**.
  </Step>

  <Step title="Connect in Overcut">
    In Overcut, open the git providers list and click the **Jira Server / Data
    Center** tile. Enter:

    * **Instance URL**: your Jira base URL (for example
      `https://jira.your-company.com`)
    * the **Client ID** and **Client Secret** from the previous step

    Make sure your browser session is signed into Jira **as the service account**,
    then click **Authorize**. Overcut captures the service-account identity and
    stores the connection.
  </Step>

  <Step title="Register the webhook in Jira">
    Webhooks are configured in Jira, separately from the Application Link. Open the
    connected org's **settings** page in Overcut (**View settings** on the provider
    page) to find the webhook **URL** (shaped like
    `https://<dispatcher>/webhooks/jira/server/<orgId>?secret=<token>`).

    In Jira, go to **Settings (cog) -> System -> WebHooks -> Create a WebHook**,
    paste the full URL (use **Copy full URL** in Overcut so the real secret is
    embedded), and under **Events** enable issue **created / updated / deleted**
    and comment **created / updated / deleted**.

    <Warning>
      Leave the webhook configured to **send the issue body** (do not exclude it).
      Overcut reads the issue description from the webhook payload; if the body is
      excluded, descriptions arrive empty.
    </Warning>

    Leave the JQL filter empty to receive all projects, or scope it. Save.
  </Step>
</Steps>

## Deployment configuration

These settings are configured once by whoever operates the self-hosted Overcut
deployment.

| Setting                           | Value                                                         | Notes                                                                                   |
| --------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `INTEGRATION_JIRA_SERVER_ENABLED` | `true`                                                        | Set on both the server and workflow-dispatcher to enable the tile and inbound webhooks. |
| `JIRA_SERVER_REDIRECT_URI`        | `https://<your-overcut-domain>/jira-server-auth-app/callback` | Must equal the Application Link callback URL exactly.                                   |
| `DISPATCHER_BASE_URL`             | `https://<dispatcher-or-app>/hooks`                           | External URL used to build the webhook URL shown in Overcut.                            |

## Troubleshooting

* **`redirect_uri` mismatch at Authorize**: the Application Link callback URL and `JIRA_SERVER_REDIRECT_URI` are not byte-identical (often a trailing slash or `http` vs `https`).
* **Authorize fails to reach Jira**: the instance must be reachable from the Overcut deployment over HTTPS with a valid certificate. Confirm network access and TLS.
* **Actions attributed to the wrong person, or bot loops**: you consented as your personal account instead of the service account. Re-authorize in an incognito window signed in as the bot account.
* **Issue descriptions arrive empty**: the Jira webhook is configured to exclude the issue body. Edit the webhook so it sends the full issue payload.
* **Webhook events never fire**: confirm the webhook URL still includes `?secret=...`, the issue and comment events are enabled, and `DISPATCHER_BASE_URL` is set to the external URL with `INTEGRATION_JIRA_SERVER_ENABLED=true` on the dispatcher.

For concepts shared across all Jira setups (issue operations, status-name rules,
ticket links), see the [Jira overview](/docs/integrations/jira).