diff --git a/docs.json b/docs.json index d9a58c2d..2315ee76 100644 --- a/docs.json +++ b/docs.json @@ -531,6 +531,7 @@ "pages": [ "enterprise/integrations/azure-devops", "enterprise/integrations/bitbucket-data-center", + "enterprise/integrations/jira-cloud", "enterprise/integrations/jira-data-center", "enterprise/integrations/slack", "enterprise/integrations/external-llm-gateways" diff --git a/enterprise/integrations/jira-cloud.mdx b/enterprise/integrations/jira-cloud.mdx new file mode 100644 index 00000000..e63f32a5 --- /dev/null +++ b/enterprise/integrations/jira-cloud.mdx @@ -0,0 +1,143 @@ +--- +title: Jira Cloud +description: Configure Jira Cloud for OpenHands Enterprise. +icon: cloud +--- + +This guide explains how to connect Jira Cloud 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. +OpenHands replies on the issue with a link to the conversation and posts the +result back when it finishes. + +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](#user-requirements)). +Users are enrolled automatically the first time they trigger OpenHands. + +## Prerequisites + +- Jira Cloud **site administrator** access, to invite the service account and + register a webhook. +- 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 example +`openhands-bot@company.com`. OpenHands uses this account to read issues and +post comments, and its replies appear under this account's name. + +1. Invite the account to your Jira site and grant it access to every project + where OpenHands should read and comment. +2. 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. + + + Mentions and labels made by the service account itself are ignored to + prevent the agent from triggering itself. Always test from a regular user + account, not the service account. + + +## Enable the integration in the Admin Console + +1. In the OpenHands Enterprise Admin Console, open **Config** and check + **Enable Jira Cloud Integration** under **Jira Cloud Integration**. +2. Save and deploy the new version, and wait for the rollout to finish. + +After the deploy, a **Jira** card appears under **Settings → Integrations** +in the OpenHands app. + +## Configure the workspace in OpenHands + +As an organization admin or owner, open **Settings → Integrations → Jira** +in OpenHands and select **Configure**: + +- **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. + +Save, then copy the **events URL** shown below the webhook secret field. It +has the form: + +``` +https://app./integration/jira/events +``` + +## 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"). + +## User requirements + +Each user who wants to trigger OpenHands from Jira must satisfy two +conditions: + +1. **Matching email**: the user's Atlassian account email must exactly match + their OpenHands login email. +2. **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. + + + Atlassian can take 15 minutes or more to propagate an email-visibility + change into webhook payloads. If OpenHands replies that it could not + determine your email address right after you changed the setting, wait and + try again before assuming the setting is wrong. + + +No further setup is needed: the first successful mention enrolls the user +automatically. + +## Start OpenHands from an issue + +- Comment `@openhands` followed by instructions on any issue in a project the + webhook covers, or add the `openhands` label 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/project` or + `https://github.com/org/repo`) in the issue description or the comment. The + triggering user must have that Git provider connected in OpenHands, and + exactly one repository should be mentioned. Without a repository, OpenHands + still answers on the issue but works without a workspace. + +OpenHands reacts with a comment linking to the conversation, and the service +account posts the result back to the issue when the run completes. + +## 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-integrations` + workload) 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 to + `yourcompany.atlassian.net`. +- **OpenHands replies that multiple repositories were found**: mention + exactly one repository in the issue and comment text.