Skip to main content
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.
Not your setup? See Which setup do I need?. For Atlassian-hosted Jira Cloud, use the Forge app (Overcut Cloud) or direct OAuth (self-hosted Overcut).

​
How it differs from Jira Cloud

Jira Server / Data CenterJira Cloud
OAuth endpointsYour instance ({instance}/rest/oauth2/latest/...)Atlassian-central (auth.atlassian.com)
Authorization3LO only (browser consent)3LO or 2LO
ScopeWRITE (coarse, instance-level)read:jira-work, write:jira-work, read:jira-user
REST APIv2 (/rest/api/2)v3 + ADF
WebhookManual pasteManual 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)
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.

​
Connect

1

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

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

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.
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.
Leave the JQL filter empty to receive all projects, or scope it. Save.

​
Deployment configuration

These settings are configured once by whoever operates the self-hosted Overcut deployment.
SettingValueNotes
INTEGRATION_JIRA_SERVER_ENABLEDtrueSet on both the server and workflow-dispatcher to enable the tile and inbound webhooks.
JIRA_SERVER_REDIRECT_URIhttps://<your-overcut-domain>/jira-server-auth-app/callbackMust equal the Application Link callback URL exactly.
DISPATCHER_BASE_URLhttps://<dispatcher-or-app>/hooksExternal 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.