Jira Data Center

Configure Jira Data Center for OpenHands Enterprise.

This guide explains how to connect Jira Data Center to an OpenHands Enterprise Replicated installation. The integration lets users start OpenHands from Jira issues by commenting with @openhands or by adding the openhands label.

Prerequisites

• Jira Data Center administrator access to create users, personal access tokens, OAuth applications, and webhooks.
• Network access from OpenHands to Jira Data Center for API calls, and from Jira Data Center back to the OpenHands app URL for webhook delivery.
• If Jira Data Center uses an internal or self-signed certificate, upload the issuing CA in the OpenHands Enterprise Admin Console under Additional Trusted CA Certificates before deploying.

Jira Data Center setup is global for the OpenHands Enterprise installation. Service account values are configured in the Admin Console. Webhook setup is completed later inside OpenHands.

Create a Bot Token

Create a dedicated Jira user for OpenHands. For example, create a user named openhands with an email address such as [e-mail]. OpenHands uses this bot account to read issues, add comments, and add reactions. Grant it access to all Jira projects where OpenHands should read and comment.

Next, sign in as the openhands user and create a Jira personal access token from the user’s profile. This is the Jira bot token. Store it securely. You will need to paste the bot account email and PAT into the OpenHands Enterprise Admin Console.

Create a Jira OAuth Application

OAuth linking is recommended because it lets team members prove ownership of their Jira account before using OpenHands to process their Jira events.

In Jira Data Center, open Administration > Applications > Application links and create a new link. When Jira asks what type of application to connect, choose External application. For the direction, choose Incoming because OpenHands connects to Jira during OAuth linking.

Configure the incoming link with this callback URL:

https://app.<your-openhands-domain>/integration/jira-dc/callback

Use your actual app hostname, for example:

https://app.openhands.example.com/integration/jira-dc/callback

Select the WRITE scope if Jira asks for scopes or permissions.

Copy the OAuth client ID and client secret and store them securely. You will paste them into the Admin Console.

If your Jira Data Center installation cannot provide an OAuth application, you can select email matching in the Admin Console instead. In that mode, OpenHands links Jira users by matching their Jira email address to their OpenHands email address.

Configure the Admin Console

Open the Replicated Admin Console for your OpenHands Enterprise installation and go to the application configuration page.

In Jira Data Center Integration:

1. Enable Jira Data Center Integration.
2. Select the user linking method:
   • OAuth is recommended.
   • Email match can be used if OAuth is not available.
3. Enter the Jira Data Center Service Account Email.
4. Enter the Jira Data Center Service Account PAT.
5. If using OAuth, enter the Jira Data Center Base URL, including https://.
6. If using OAuth, enter the Jira Data Center OAuth Client ID and OAuth Client Secret.
7. Save and deploy the updated configuration.

The Jira Data Center Base URL must include the scheme, for example https://jira.example.com. Do not enter only jira.example.com.

Install the Jira Webhook

After OpenHands is deployed, sign in to OpenHands and open Settings > Integrations > Jira Data Center.

If OAuth is enabled, click Connect and complete the Jira OAuth flow. Then set up the webhook using one of the options below.

Automatic setup

Choose Install automatically and paste a short-lived Jira admin PAT. OpenHands uses this PAT once to call Jira’s webhook API and then discards it. The PAT is never stored. The automatic setup creates or updates a Jira global webhook named OpenHands that points to this OpenHands URL.

https://app.<your-openhands-domain>/integration/jira-dc/connections/<connection-id>/events

Manual setup

Choose Set it up in Jira myself, then click Generate webhook details. OpenHands saves the connection and shows a webhook URL and signing secret.

In Jira Data Center, create a global webhook using those generated values. Use these events:

• jira:issue_created
• jira:issue_updated
• jira:issue_deleted
• comment_created
• comment_updated
• comment_deleted

After saving the webhook in Jira, return to OpenHands and click I created the webhook.

Link Users

Each user who wants to invoke OpenHands from Jira should sign in to OpenHands and connect their Jira Data Center account from Settings > Integrations > Jira Data Center.

When a Jira event arrives, OpenHands resolves the Jira user to an OpenHands user. If a user has an OpenHands account but has not linked Jira Data Center, OpenHands will comment on the issue asking the user to link their account and try again.

Trigger OpenHands from Jira

Create or update a Jira issue with clear requirements. Include the target repository in the issue description or in a follow-up comment, for example:

Repository: Acme/web-app

Then trigger OpenHands with either:

• A Jira comment containing @openhands.
• The openhands label on the issue.

The invoking OpenHands user must have access to the target repository written in the Jira issue. If OpenHands cannot determine or access the repository, it comments on the issue with the next step to fix the repository reference or access.

Troubleshooting

Symptom	Check
The Jira Data Center card is not visible in OpenHands	Confirm Jira Data Center Integration is enabled in the Admin Console and the deployment has been applied.
OAuth redirects fail	Confirm the Jira OAuth callback URL exactly matches https://app.<your-openhands-domain>/integration/jira-dc/callback.
Automatic webhook setup fails	Confirm the admin PAT belongs to a Jira user allowed to create global webhooks.
Webhook deliveries return 403	Confirm the webhook URL and signing secret match the values generated by OpenHands.
Webhook deliveries reach OpenHands but no job starts	Confirm the Jira user is linked, the integration is active, the comment contains @openhands or the issue update added the openhands label, and the user has access to the repository.
OAuth, issue reads, or automatic webhook setup fail with connection errors	Confirm the OpenHands cluster can reach the Jira Data Center URL.
Jira webhook deliveries do not reach OpenHands	Confirm the Jira Data Center network can reach the OpenHands app URL.
Jira API calls fail with TLS errors	Upload the Jira Data Center CA certificate in Additional Trusted CA Certificates and redeploy.