docs(enterprise): add Slack integration guide for self-hosted OHE

[jpshackelford]

What

Adds enterprise/integrations/slack.mdx documenting how to enable the @OpenHands Slack resolver on a self-hosted OpenHands Enterprise install (both the Replicated VM-based install and standalone Helm). Wires the new page into the Enterprise tab under a new "Integrations" group in docs.json.

Why

The Slack resolver has shipped for self-hosted OHE — the chart wiring landed in OpenHands/OpenHands-Cloud#584 (ALL-5659) and the Slack-App creation script landed in OpenHands/OpenHands-Cloud#601 (PLTF-2036) — but the docs site only documents the Cloud flow (openhands/usage/cloud/slack-installation), which uses the All-Hands-managed Slack App and is not applicable to customers running their own install.

Today the operator-facing information is split across:

• inline help_text strings in the Replicated admin console,
• scripts/create_slack_app/README.md in OpenHands-Cloud,
• and reading the chart templates directly.

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

Contents of the new page

End-to-end, in order:

1. Prerequisites — public HTTPS reachability, valid TLS, Slack workspace admin available. Explicitly calls out that air-gapped installs are not supported (Socket Mode is disabled).
2. Step 1 — Create the Slack App. Two options:
   • Option A (recommended): run scripts/create_slack_app/create_slack_app.py from OpenHands-Cloud with --base-domain <your-domain> and a Slack App Configuration Token, which mints the app via apps.manifest.create and prints Client ID, Client Secret, Signing Secret.
   • Option B: paste an equivalent YAML manifest into Slack's "Create New App → From an app manifest" UI for workstations without outbound access to slack.com.
     Documents all four webhook URLs registered on the app (/slack/install-callback, /slack/on-event, /slack/on-form-interaction, /slack/on-options-load), the bot scopes, and the disabled flags (Socket Mode, Org Deploy, Token Rotation).
3. Step 2 — Configure OHE. Tabbed instructions for:
   • Replicated: enable the new "Enable Slack" config group and paste the three credentials. Explains the resulting slack-auth Secret, the slack.enabled / slack.clientId Helm values, and the ENABLE_V1_SLACK_RESOLVER=true env var that the Replicated overlay sets.
   • Standalone Helm: equivalent values.yaml snippets for the openhands and openhands-secrets charts, plus a note for operators who manage the slack-auth Secret directly.
     Ends with a kubectl set env … --list one-liner to verify the integrations pod restarted with SLACK_* env vars.
4. Step 3 — Install the app into the workspace via https://app.<your-base-domain>/slack/install. Notes the missing_scope recovery path.
5. Step 4 — Per-user account linking. Either via OpenHands' Settings → Integrations or by mentioning @openhands once and clicking the login link the bot replies with. Explains that the link populates the slack_users table and that conversations then run as that OpenHands user (their LLM keys, provider tokens, org).
6. Usage — defers to the existing Cloud page's "Working With the Slack App" section for UX/screenshots and calls out three self-hosted specifics: repo selection via /slack/on-options-load, thread ownership (only the original asker can @openhands in follow-up replies), and conversation-link URLs.
7. Limitations — no Socket Mode, no token rotation, single Slack App per install, Slack Connect channels not supported.
8. Troubleshooting — accordion with the most likely failure modes:
   • URL verification ("Your URL didn't respond with the value of the challenge parameter")
   • mentions are ignored / SLACK_WEBHOOKS_ENABLED missing
   • users get a login link every time (with a psql query to verify the link row)
   • missing_scope in pod logs
   • rotating Slack credentials
9. Reference — links to the helper script, Replicated config group, and chart values in OpenHands-Cloud, plus the Cloud Slack page for end-user UX.

Navigation

docs.json gets a new "Integrations" group under the Enterprise tab. It's intentionally separate from "K8s Install" so future enterprise integrations (Jira DC, Bitbucket DC, etc.) can land alongside Slack without further nav churn.

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

llms.txt / llms-full.txt

make llms was run per the repo's AGENTS.md guidance. The new page is included, but the regenerator also picks up pre-existing drift from other recently-merged PRs (org pages, skills pages, an automations description tweak, etc.). The weekly check-llms-files.yml sync workflow would have produced the same diff. If reviewers would rather keep this PR minimal, I'm happy to revert the llms changes and let the weekly job handle them — let me know.

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/slack-installation#working-with-the-slack-app).
• All external links point at public OpenHands-Cloud repository paths under main.

Out of scope

• No content changes to the existing Cloud Slack page (openhands/usage/cloud/slack-installation.mdx) — I deliberately left it focused on Cloud and added an <Info> cross-link from the new enterprise page rather than rewriting the Cloud one.
• No screenshots of the Replicated admin console; happy to add them in a follow-up once we have a clean staging install to grab them from.

---

This PR was opened by an AI agent (OpenHands) on behalf of the requesting user.

@jpshackelford can click here to continue refining the 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, 3:22 PM

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

[jpshackelford]

Rebased onto main (was branched off 1d26cb1, now sitting on b6fc708).

How the docs.json collision with #532 was resolved. Both PRs introduced a new "group": "Integrations" block under the Enterprise tab — Alona's #532 (squash-merged as 6c60925) with [bitbucket-data-center, jira-data-center], this one with [slack]. Git's text merge "succeeded" by leaving two parallel Integrations groups in the Enterprise tab, which is wrong. I merged them into a single group with pages sorted alphabetically by basename. The Enterprise tab is now:

[0] OpenHands Enterprise
[1] Integrations  ['enterprise/integrations/bitbucket-data-center',
                   'enterprise/integrations/jira-data-center',
                   'enterprise/integrations/slack']
[2] K8s Install

Net docs.json diff vs main is now a single line — appending enterprise/integrations/slack to Alona's existing group:

             "group": "Integrations",
             "pages": [
               "enterprise/integrations/bitbucket-data-center",
-              "enterprise/integrations/jira-data-center"
+              "enterprise/integrations/jira-data-center",
+              "enterprise/integrations/slack"
             ]

llms.txt / llms-full.txt regenerated via make llms per AGENTS.md. make llms-check passes (no drift). As mentioned in the original PR body, the regenerator picks up content that landed on main since this branch was cut (QA Testing page #529, org pages, skills pages, Plugins, Analytics, External PostgreSQL, both Data Center integration pages, plus a couple of description edits to Automations Overview / LLM Settings). The weekly check-llms-files.yml sync would have produced the same diff — happy to drop the llms files from this PR if reviewers would prefer the weekly job handle them.

Verification.

• python3 -c "import json; json.load(open('docs.json'))" — JSON syntax OK.
• make llms-check — exit 0, no drift.
• git diff --stat origin/main...HEAD:
  • docs.json 3 ±
  • enterprise/integrations/slack.mdx 385 + (new)
  • llms.txt 18 ±
  • llms-full.txt 3866 ±

PR is now mergeable (was CONFLICTING, now MERGEABLE per the GitHub API).

---

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