Add Enterprise Data Center integration guides

[ak684]

Summary

Adds OpenHands Enterprise docs for Bitbucket Data Center and Jira Data Center setup, plus quick-start links for both integrations. The guides cover Admin Console configuration, OAuth app setup, bot/service account tokens, webhook setup, user linking, troubleshooting, and screenshots.

Validation

• python3 -m json.tool docs.json >/dev/null
• git diff --check
• Mintlify checks were green on Add Enterprise Data Center integration guides #528 for the same content before opening this clean PR

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	May 27, 2026, 11:03 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

This is a well-structured, thorough addition to the Enterprise docs. Both integration guides are clear, consistently formatted, and include the right mix of prerequisites, step-by-step instructions, screenshots, and troubleshooting tables. The docs.json navigation restructuring and the quick-start additions are also well done.

Two items worth a look before merging — one potential inaccuracy on the Jira webhook REST API path, and one minor suggestion to help admins understand what they're granting with the WRITE OAuth scope.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

This is a solid set of integration guides — both the Bitbucket Data Center and Jira Data Center docs are well-structured, thorough, and include the right balance of prerequisites, step-by-step instructions, screenshots, and troubleshooting tables. The docs.json restructuring and the quick-start additions are clean.

Two items from the previous review remain open (Jira webhook REST API path, and the WRITE scope clarification); those are worth resolving before merging. Two additional observations are noted inline below.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

Documentation quality here is high — both guides follow a clear, consistent structure with prerequisites, step-by-step admin configuration, user-facing sign-in and webhook setup, and troubleshooting tables. The docs.json navigation restructuring is clean, and the quick-start updates make the LLM configuration appropriately provider-agnostic.

Previously raised items (still unresolved)

Three threads from earlier reviews remain open and should be resolved before merge:

1. Jira webhook REST API path (enterprise/integrations/jira-data-center.mdx line 161): The endpoint POST /rest/jira-webhook/1.0/webhooks should be verified against Atlassian documentation. The standard dynamic webhook endpoint is /rest/webhooks/1.0/webhook. If this is a version-specific or plugin-supplied endpoint, a version note or explanation would prevent admins from hitting 404s on vanilla installs.

2. WRITE OAuth scope clarification (enterprise/integrations/jira-data-center.mdx): Worth adding a brief parenthetical describing what access this scope actually grants.

3. EXCLUDE_BODY flag explanation (enterprise/integrations/jira-data-center.mdx line 181): A sentence explaining why this must be false (otherwise Jira omits issue/comment bodies from webhook payloads) would help admins who copy-paste only the shell command.

New observation

One item in the Bitbucket guide is flagged inline below — the Keycloak broker alias in the OAuth callback URL should be confirmed against the actual allhands realm configuration before this guide goes live.

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

Pure documentation addition with no code changes. The main risk is documentation inaccuracies that cause admins to misconfigure their installations. The Jira webhook endpoint concern (🟠 from the previous review) remains the highest-risk open item — an incorrect API path produces setup failures with no clear error message. The Bitbucket broker alias question (noted inline) is in the same category.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[all-hands-bot]

🟡 Verify the Keycloak IDP broker alias

The callback URL uses bitbucket_data_center (underscores) as the Keycloak identity provider broker alias. Keycloak broker aliases are case-sensitive and must exactly match the IDP alias configured in the OpenHands Enterprise allhands realm. If the actual realm configuration uses bitbucket-data-center (dashes) or another name, users would receive OAuth redirect errors that are difficult to diagnose.

Please confirm this alias matches the value in the realm's IDP settings. The troubleshooting entry "OAuth redirects fail" already covers this case — which is good — but an accurate URL here should make that entry unnecessary for a correctly set-up installation.

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

Summary of changes reviewed

This is a clean port of the Enterprise Data Center integration content from #528. Both the Bitbucket Data Center and Jira Data Center guides are well-structured and follow the established docs pattern: prerequisites, step-by-step admin setup, user-facing flows, and troubleshooting tables. The docs.json navigation restructuring and the provider-agnostic quick-start updates are clean.

---

Resolution of prior review concerns

All three issues raised in earlier reviews are no longer present in this clean PR:

• ✅ The POST /rest/jira-webhook/1.0/webhooks endpoint reference has been removed from the Jira guide.
• ✅ The EXCLUDE_BODY flag discussion has been removed from the Jira guide.
• ✅ The WRITE OAuth scope now has a descriptive parenthetical: "allows OpenHands to link Jira accounts and make Jira API calls within the user's granted Jira permissions".
• ✅ The Additional Integrations section in quick-start.mdx is placed correctly before the "click Continue" instruction — admins see it as a pre-deployment configuration checklist, which is the right read-order.

---

Remaining actionable item

One concern from the prior reviews is still present and flagged inline: the Keycloak broker alias bitbucket_data_center in the Bitbucket OAuth callback URL needs to be confirmed against the actual allhands realm configuration before the guide goes live. An incorrect alias causes silent 404 failures for all Bitbucket DC logins — confirm the alias once and this is ready to ship.

---

Minor observations (non-blocking)

• Navigation ordering in docs.json: The new "Integrations" group is placed before the existing "K8s Install" group. Since K8s Install is the core deployment method and Integrations are optional add-ons, reversing the order (K8s Install → Integrations) might reflect a more logical setup sequence. This is purely cosmetic and does not affect functionality.
• Jira label-triggered jobs: The guide says the openhands label can trigger a job, but it does not clarify who is the "invoking user" when a label is added (vs. a comment with @openhands). If user resolution differs for label-triggered events (e.g., uses the label adder vs. the service account), a brief note would help admins understand the permissions model.

---

Overall risk assessment

🟢 LOW risk — pure documentation addition with no code changes. Content is accurate and well-written. The one outstanding actionable item (Bitbucket Keycloak broker alias) is low-effort to verify and has no impact if confirmed correct.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[all-hands-bot]

🟡 Verify the Keycloak IDP broker alias (carry-over from prior reviews)

The callback URL uses bitbucket_data_center (underscores) as the Keycloak identity provider alias. Keycloak broker aliases are case-sensitive and deployment-specific — they depend on how the IDP was registered in the allhands realm. If the actual alias uses hyphens, different casing, or a shorter name, OAuth callbacks will return a 404 and all Bitbucket DC logins will fail silently.

Please confirm this alias matches exactly what is configured in your production Keycloak realm before this guide goes live. If the alias varies by deployment, a note calling this out (and pointing admins to check their Keycloak realm config) would prevent misconfiguration.