@openhands or by adding the openhands label.
OpenHands replies on the issue with a link to the conversation and posts the
result back when it finishes.
The resolver is also available on a
standalone Helm installation.
Jira Cloud users are linked to OpenHands accounts by email match: no
Atlassian OAuth app is required, and users need no per-user setup beyond
making their email visible (see User requirements).
Users are enrolled automatically the first time they trigger OpenHands.
To trigger an automation from a Jira event instead, register a separate
custom webhook.
The resolver webhook described below does not deliver events to automations.
Prerequisites
- Jira Cloud site administrator access, to invite the service account and register a webhook. The account creating the system webhook needs Administer Jira permission; the service account only needs project access.
- An OpenHands Enterprise organization admin or owner account, to configure the integration inside OpenHands.
- Network access from Jira Cloud to the OpenHands app URL over HTTPS with a
publicly trusted certificate (for webhook delivery), and from OpenHands to
api.atlassian.com(for Jira API calls).
Create a service account
Create a dedicated Atlassian account for OpenHands, for exampleopenhands-bot@company.com. OpenHands uses this account to read issues and
post comments, and its replies appear under this account’s name.
- Invite the account to your Jira site and grant it access to every project where OpenHands should read and comment.
- Log in as the service account and create an API token at id.atlassian.com → Security → API tokens. Save the token somewhere safe. You will need it for the next configuration step below.
Enable the integration in the Admin Console
- In the OpenHands Enterprise Admin Console, open Config and check Enable Jira Cloud Integration under Jira Cloud Integration.
- Save and deploy the new version, and wait for the rollout to finish.
Enable the integration with Helm
For a standalone Helm installation, enable the same resolver in your existingvalues.yaml:
Configure the workspace in OpenHands
As an organization admin or owner, open Settings → Integrations → Jira in OpenHands and select Configure. On a new installation, the Link Workspace screen appears first. Enter the workspace hostname and select Connect. Then complete the administrator form:- Workspace: the full site hostname, for example
yourcompany.atlassian.net. Webhook events are matched against this hostname, so the bare site name is not sufficient. - Service account email: the service account’s email address.
- Service account API token: the token created above. The credentials are validated against Jira when you save, so a typo fails immediately.
- Webhook secret: choose a strong secret. You will paste the same secret into Jira in the next step.
Register the webhook in Jira
In Jira, open Settings (gear icon) → System → WebHooks and create a webhook:- URL: the events URL copied above.
- Secret: the same webhook secret entered in OpenHands. Jira uses it to sign deliveries, and OpenHands rejects unsigned or mis-signed events.
- Events: check Issue → updated and Comment → created. These are the only two events OpenHands processes.
- Optionally scope the webhook with a JQL filter (for example
project = ENG). - Leave the request body included (do not check “Exclude body”).
@openhands followed by a read-only request. Confirm that OpenHands
posts a conversation link on that issue.
User requirements
Each user who wants to trigger OpenHands from Jira must satisfy two conditions:- Matching email: the user’s Atlassian account email must exactly match their OpenHands login email.
- Visible email: in the user’s Atlassian account settings (id.atlassian.com → Profile and visibility → Contact → Email address), visibility must be set to Anyone. Jira omits the email from webhook payloads otherwise, and OpenHands cannot match the user without it.
Start OpenHands from an issue
Starting with several repositories is supported in OpenHands Enterprise 0.103.0 and later.
- Comment
@openhandsfollowed by instructions on any issue in a project the webhook covers, or add theopenhandslabel to the issue. Both the typed literal text and the mention selected from Jira’s autocomplete picker work. - To have OpenHands work in a repository, include the repository URL (for
example
https://gitlab.com/group/projectorhttps://github.com/org/repo) in the issue description or the comment. The triggering user must have that Git provider connected in OpenHands. Without a repository, OpenHands still answers on the issue, but no repository is checked out. - To work across several repositories, mention each of them. OpenHands starts one conversation with all the repositories it can access, up to ten. Repositories named in the comment come first, then those in the issue description. The first accessible one becomes the main repository, and the others are cloned beside it.
Trigger Automations from Jira
Jira-triggered automations use a second Jira system webhook. The resolver URL ending in/integration/jira/events only handles mentions and labels; it
does not feed the automation service.
First, enable the automation service on your installation. Follow
Custom Webhooks
to create an OpenHands API key and register a custom source. For Jira Cloud,
use a distinct source name and these registration fields:
webhook_secret, OpenHands generates one and returns it once
with the webhook_url. Store both securely. Create an event automation for
source jira-issues and event jira:issue_created, then register another Jira
system webhook using that webhook_url and signing secret. Select only
Issue created and use a narrow JQL filter, such as
project = ENG AND labels = openhands-automation. Create one matching test
issue and confirm that the automation starts. Keep this webhook separate from
the resolver webhook above.
Troubleshooting
- OpenHands replies “Could not determine your Jira email address”: the email-visibility requirement above is not met, or the change has not propagated yet. Verify the exact setting and retry after 15 minutes.
- A mention does nothing, with no reply at all: check that the comment
was not made by the service account (those are ignored), that the user’s
Atlassian email matches their OpenHands email, and that the webhook covers
the issue’s project. Jira Cloud does not show a delivery log for system
webhooks, so check the OpenHands logs (the
openhands-integrationsworkload) or collect a support bundle. - Logs show
403 Unidentified workspace: the Workspace field in the OpenHands configuration does not equal the site hostname in the webhook payload. Re-open the configuration and set it toyourcompany.atlassian.net. - OpenHands replies “Could not access any of the mentioned repositories”: no conversation was started. Check each repository name, and that the Git account connected to the triggering user’s OpenHands account can open it.

