docs(enterprise): add Jira Data Center integration guide for self-hosted OHE

[jpshackelford]

What

Adds enterprise/integrations/jira-dc.mdx documenting how to enable the Jira Data Center integration on a self-hosted OpenHands Enterprise install (both the Replicated VM-based install and standalone Helm). Wires the new page into the new "Integrations" group in docs.json introduced by #525.

⛓️ Stacked on #525 — please merge that one first.
This PR targets docs/enterprise-slack-integration rather than main because both PRs add a new top-level enterprise/integrations/ directory and the same "group": "Integrations" block in docs.json. Re-target this PR to main (or rebase) once #525 lands.

Why

The Jira Data Center integration has shipped for self-hosted OHE — the Replicated config group was wired up in OpenHands/OpenHands-Cloud#656 (Wire Jira Data Center for Replicated installs, merged 2026-05-22), and the service-account fields were added in OpenHands/OpenHands-Cloud#658 ([PLTF-2870] Add Jira DC service account KOTS config, merged 2026-05-26). The chart wiring (charts/openhands-secrets/templates/jira-dc-app.yaml, charts/openhands/templates/_env.yaml, and the /integration/jira-dc/events ingress route) is already in place.

Today the operator-facing information is split across:

• inline help_text strings in the Replicated admin console (which only an operator already in the console can read),
• the chart templates themselves,
• and the existing Cloud-flavored placeholder at openhands/usage/cloud/project-management/jira-dc-integration.mdx (titled "Jira Data Center Integration (Coming soon...)", not yet linked from docs.json nav).

This PR consolidates the end-to-end self-hosted workflow on docs.openhands.dev so an operator can stand up Jira DC against a fresh OHE install without reading chart source code.

Contents of the new page

End-to-end, in order:

1. Prerequisites — bidirectional HTTPS reachability between OHE and Jira DC, valid TLS on both sides, a Jira DC admin available. Explicitly notes that air-gapped Jira installs are not supported.
2. Step 1 — Set up Jira Data Center. Three sub-steps:
   • Create the service account. Bot user openhands-agent with Browse Projects + Add Comments permissions on every project OpenHands should work on. No admin or "Bulk Change" required.
   • Generate the service-account PAT. From the bot user's Profile → Personal Access Tokens. Used by OpenHands to read tickets and post comments as the service account.
   • Create the OAuth 2.0 application (only when linkMethod=oauth). Documents the exact callback URL https://app.<your-base-domain>/integration/jira-dc/callback, plus a <Warning> about the exact-match requirement.
     Includes a leading table that maps each artifact (Service Account Email / PAT / OAuth Client ID / Secret / Base URL) to which link method requires it.
3. Step 2 — Configure OHE. Tabbed instructions for:
   • Replicated: enable the new Jira Data Center Integration config group and paste the seven fields shown in the KOTS admin console. Explains the resulting Secret/jira-dc-app, the jiraDc.enabled / jiraDc.linkMethod Helm values, and the auto-mirrored OH_WEB_CLIENT_FEATURE_FLAGS_ENABLE_JIRA_DC frontend feature flag.
   • Standalone Helm: equivalent values.yaml snippets for the openhands and openhands-secrets charts. Explicitly calls out the OH_WEB_CLIENT_FEATURE_FLAGS_ENABLE_JIRA_DC gotcha — without setting it, the backend routes are live but the UI card never renders (this gotcha is auto-handled by the Replicated overlay; Helm users have to set it themselves).
     Ends with a kubectl set env … --list one-liner showing the expected JIRA_DC_* env vars for both linkMethod=oauth and linkMethod=email installs.
4. Step 3 — Create the webhook in Jira Data Center. Points Jira at https://app.<your-base-domain>/integration/jira-dc/events with Issue updated + Comment created events. Explains that JQL filtering is optional and that OHE re-fetches issues via the service-account PAT before acting, so no shared webhook secret is required.
5. Step 4 — Per-user account linking via Settings → Integrations → Jira Data Center. Walks through the OAuth redirect flow vs the email-match fast path, and clarifies that the first user to register a workspace pastes the service-account credentials once on behalf of the deployment (mirroring the existing Cloud placeholder doc's UX), while subsequent users do not.
6. Usage — label trigger (openhands label) vs mention trigger (@openhands …), an example ticket body with repo coordinates and AC, and a clarification that conversations run as the linked user, using their LLM keys / Git tokens / org — the openhands-agent service account is only used to read the ticket and post the bot's @openhands replies.
7. Limitations — no air-gapped operation, no PAT rotation, single Jira server per install, email-match link method trust assumptions, service-account permission scoping.
8. Troubleshooting — accordion with the most likely failure modes:
   • integration card missing from Settings → Integrations (the OH_WEB_CLIENT_FEATURE_FLAGS_ENABLE_JIRA_DC gotcha)
   • webhook events not arriving (path typo / firewall / TLS)
   • OAuth redirect_uri does not match
   • @openhands mentions ignored
   • email-match link "succeeds" but @openhands still asks to re-link (with a psql query to diagnose)
   • rotating the service-account PAT or OAuth client secret
9. Reference — deep links to the Replicated config group, chart values, secret template, env-var template, and ingress route in OpenHands-Cloud, plus a cross-link back to the existing Cloud placeholder.

Navigation

docs.json gets the new page appended to the "Integrations" group introduced by #525:

{
  "group": "Integrations",
  "pages": [
    "enterprise/integrations/slack",
    "enterprise/integrations/jira-dc"
  ]
}

llms.txt / llms-full.txt

make llms was run per the repo's AGENTS.md guidance. Because this PR is stacked on top of #525 (which already absorbed the pre-existing drift mentioned there), the diff here is clean — +1 line in llms.txt and +468 lines in llms-full.txt, all of which are the new Jira DC page body.

Verification

• python3 -c "import json; json.load(open('docs.json'))" — JSON syntax OK.
• npx mintlify@latest broken-links — success no broken links found.
• All internal links target existing pages (/enterprise/quick-start, /enterprise/k8s-install/index, /openhands/usage/cloud/project-management/jira-dc-integration).
• All four internal anchor links (#create-the-service-account, #generate-the-service-account-pat, #create-the-oauth-20-application, #step-2-configure-openhands-enterprise) resolve to real headings in the page.
• All external links point at public OpenHands-Cloud paths under main.

Out of scope

• No content changes to the existing Cloud placeholder (openhands/usage/cloud/project-management/jira-dc-integration.mdx, currently titled "Jira Data Center Integration (Coming soon...)" and not linked from docs.json). PR #451 renames that file under enterprise/usage/cloud/project-management/; this new self-hosted page is intentionally separate and lives under enterprise/integrations/ alongside Slack, exactly the way docs(enterprise): add Slack integration guide for self-hosted OHE #525 anticipated.
• No screenshots of the Replicated admin console or the Settings → Integrations card. Happy to add them in a follow-up once we have a clean staging install to grab them from.

Coordination

PR	Author	Overlap with this PR	Action
#525	@jpshackelford	Introduces enterprise/integrations/ + the "Integrations" group. This PR is stacked on top.	Merge #525 first; this PR will then re-target main cleanly.
#451	@enyst	Renames the Cloud Jira DC placeholder under enterprise/usage/cloud/project-management/. No content overlap with this PR — different file, different path, different audience.	Both can land independently; only docs.json will need a mechanical rebase.

---

This PR was opened by an AI agent (OpenHands) on behalf of @jpshackelford.

@jpshackelford can click here to continue refining the PR

[jpshackelford]

Closing — superseded by #532, which shipped enterprise/integrations/jira-data-center.mdx and made that page the canonical Jira Data Center guide on docs.openhands.dev.

The deeper-dive material in this PR that isn't yet on Alona's page — standalone Helm install path, the OH_WEB_CLIENT_FEATURE_FLAGS_ENABLE_JIRA_DC gotcha, kubectl env-based verification one-liner, source-of-truth reference deep-links, and the email-match re-link / credential-rotation troubleshooting recipes — is now tracked as a follow-up in #537, framed as additive sections on top of #532 rather than a replacement.

Closing #527 also unblocks #525 (Slack integration) from the stacked nav-group conflict — it can now retarget cleanly to main.

---

This comment was posted by an AI agent (OpenHands) on behalf of @jpshackelford.