Jira Cloud: describe starting one conversation with several repositories

enterprise/integrations/jira-cloud.mdx

@@ -1,11 +1,11 @@
 ---
 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.
@@ -13,33 +13,33 @@
 The resolver is also available on a
 [standalone Helm installation](#enable-the-integration-with-helm).
 
 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.
 
 To trigger an **automation** from a Jira event instead, register a separate
 [custom webhook](/openhands/usage/automations/event-automations#custom-webhooks).
 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 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
@@ -54,10 +54,10 @@
 ## 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.
 
 ## Enable the integration with Helm
@@ -79,27 +79,27 @@
   --values values.yaml
 ```
 
 Wait for the rollout to finish. The **Jira** card then appears under
 **Settings → Integrations** in the OpenHands app. Enter the service account
 credentials and webhook secret in OpenHands, not in Helm values.
 
 ## 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.
 
 After saving, the Jira card shows **Edit** for changes to this connection.
 
 Save, then copy the **events URL** shown below the webhook secret field. It
 has the form:
@@ -108,13 +108,13 @@
 https://app.<your-openhands-domain>/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.
@@ -122,25 +122,25 @@
   `project = ENG`).
 - Leave the request body included (do not check "Exclude body").
 
 Use a regular Jira account to test the resolver after completing the
 [user requirements](#user-requirements). On an issue covered by the webhook,
 comment `@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:
 
 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.
 
 <Warning>
   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.
@@ -153,31 +153,40 @@
 
 - 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.
+  triggering user must have that Git provider connected in OpenHands. Without
+  a repository, OpenHands still answers on the issue but works without a
+  workspace.
+- 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 one becomes the main repository and the others are
+  cloned beside it.
+
+OpenHands reacts with a comment linking to the conversation and naming the
+repositories it started with. The same comment lists any repository from your
+comment that it could not access, and any beyond the limit of ten. If none of
+the mentioned repositories can be accessed, OpenHands says so and does not
+start. The service account posts the result back to the issue when the run
+completes.
 
 ## 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](/openhands/usage/automations/event-automations#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:
 
 ```json
 {
   "name": "Jira issue events",
   "source": "jira-issues",
   "event_key_expr": "webhookEvent",
   "signature_header": "X-Hub-Signature"
@@ -200,13 +209,15 @@
   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.
+- **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.