diff --git a/docs.json b/docs.json index 548487e1..09aa9485 100644 --- a/docs.json +++ b/docs.json @@ -438,11 +438,23 @@ { "tab": "Enterprise", "pages": [ - "enterprise/index", - "enterprise/enterprise-vs-oss", - "enterprise/quick-start", - "enterprise/analytics", - "enterprise/external-postgres", + { + "group": "OpenHands Enterprise", + "pages": [ + "enterprise/index", + "enterprise/enterprise-vs-oss", + "enterprise/quick-start", + "enterprise/analytics", + "enterprise/external-postgres" + ] + }, + { + "group": "Integrations", + "pages": [ + "enterprise/integrations/bitbucket-data-center", + "enterprise/integrations/jira-data-center" + ] + }, { "group": "K8s Install", "pages": [ diff --git a/enterprise/images/bitbucket-data-center-application-links.png b/enterprise/images/bitbucket-data-center-application-links.png new file mode 100644 index 00000000..8d0384db Binary files /dev/null and b/enterprise/images/bitbucket-data-center-application-links.png differ diff --git a/enterprise/images/bitbucket-data-center-bot-token.png b/enterprise/images/bitbucket-data-center-bot-token.png new file mode 100644 index 00000000..26148b27 Binary files /dev/null and b/enterprise/images/bitbucket-data-center-bot-token.png differ diff --git a/enterprise/images/bitbucket-data-center-incoming-link.png b/enterprise/images/bitbucket-data-center-incoming-link.png new file mode 100644 index 00000000..835cabd6 Binary files /dev/null and b/enterprise/images/bitbucket-data-center-incoming-link.png differ diff --git a/enterprise/images/jira-data-center-create-incoming-link.png b/enterprise/images/jira-data-center-create-incoming-link.png new file mode 100644 index 00000000..271a2f98 Binary files /dev/null and b/enterprise/images/jira-data-center-create-incoming-link.png differ diff --git a/enterprise/images/jira-data-center-incoming-link-form.png b/enterprise/images/jira-data-center-incoming-link-form.png new file mode 100644 index 00000000..3309a12f Binary files /dev/null and b/enterprise/images/jira-data-center-incoming-link-form.png differ diff --git a/enterprise/images/jira-data-center-manual-webhook.png b/enterprise/images/jira-data-center-manual-webhook.png new file mode 100644 index 00000000..917355cd Binary files /dev/null and b/enterprise/images/jira-data-center-manual-webhook.png differ diff --git a/enterprise/images/jira-data-center-oauth-credentials.png b/enterprise/images/jira-data-center-oauth-credentials.png new file mode 100644 index 00000000..4c67c0c8 Binary files /dev/null and b/enterprise/images/jira-data-center-oauth-credentials.png differ diff --git a/enterprise/images/jira-data-center-openhands-comment.png b/enterprise/images/jira-data-center-openhands-comment.png new file mode 100644 index 00000000..076aad30 Binary files /dev/null and b/enterprise/images/jira-data-center-openhands-comment.png differ diff --git a/enterprise/images/jira-data-center-personal-access-token-permissions.png b/enterprise/images/jira-data-center-personal-access-token-permissions.png new file mode 100644 index 00000000..fb90a8b1 Binary files /dev/null and b/enterprise/images/jira-data-center-personal-access-token-permissions.png differ diff --git a/enterprise/images/llm-configuration-provider-dropdown.png b/enterprise/images/llm-configuration-provider-dropdown.png new file mode 100644 index 00000000..cac24045 Binary files /dev/null and b/enterprise/images/llm-configuration-provider-dropdown.png differ diff --git a/enterprise/index.mdx b/enterprise/index.mdx index decaec9c..b075a64b 100644 --- a/enterprise/index.mdx +++ b/enterprise/index.mdx @@ -56,8 +56,8 @@ agreements and API keys. OpenHands Enterprise integrates with your existing enterprise ecosystem: - **Identity & Access**: Enterprise SAML/SSO for centralized authentication -- **Source Control**: GitHub Enterprise, GitLab, Bitbucket -- **Project Management**: Jira and other ticketing systems +- **Source Control**: GitHub Enterprise, GitLab, and [Bitbucket Data Center](/enterprise/integrations/bitbucket-data-center) +- **Project Management**: [Jira Data Center](/enterprise/integrations/jira-data-center) and other ticketing systems - **Communication**: Slack integration for notifications and workflows ### Containerized Sandbox Runtime diff --git a/enterprise/integrations/bitbucket-data-center.mdx b/enterprise/integrations/bitbucket-data-center.mdx new file mode 100644 index 00000000..c20e5a0d --- /dev/null +++ b/enterprise/integrations/bitbucket-data-center.mdx @@ -0,0 +1,151 @@ +--- +title: Bitbucket Data Center +description: Configure Bitbucket Data Center authentication and repository webhooks for OpenHands Enterprise. +icon: code-branch +--- + +This guide explains how to connect Bitbucket Data Center to an OpenHands +Enterprise Replicated installation. The integration lets users sign in with +Bitbucket Data Center, open repositories, and invoke OpenHands from pull request +comments. + +## Prerequisites + +- A Bitbucket Data Center administrator who can create an OAuth 2.0 Application + Link. +- Bitbucket Data Center with OAuth 2.0 Application Links enabled. If the + application link flow does not show incoming OAuth 2.0 settings, verify your + Bitbucket Data Center version and application link settings. +- Repository administrator access for users who will install repository + webhooks from OpenHands. +- Network access from OpenHands to Bitbucket Data Center for API calls, and + from Bitbucket Data Center back to the OpenHands app URL for webhook delivery. +- If Bitbucket Data Center uses an internal or self-signed certificate, upload + the issuing CA in the OpenHands Enterprise Admin Console under **Additional + Trusted CA Certificates** before deploying. + +## Create a Bitbucket OAuth Application Link + +In Bitbucket Data Center, create an OAuth 2.0 Application Link for OpenHands. +The exact menu labels can vary by Bitbucket version, but this is usually under +**Administration > Application Links**. + +![Bitbucket Data Center Application Links settings](../images/bitbucket-data-center-application-links.png) + +Use this callback URL: + +```text +https://auth.app./realms/allhands/broker/bitbucket_data_center/endpoint +``` + +Use your actual auth hostname, for example: + +```text +https://auth.app.openhands.example.com/realms/allhands/broker/bitbucket_data_center/endpoint +``` + +OpenHands requests the `REPO_ADMIN` OAuth scope so it can list repositories and +install or refresh repository webhooks from the OpenHands UI. Copy the client ID +and client secret. You will paste them into the OpenHands Enterprise Admin +Console. + + + `REPO_ADMIN` is required so OpenHands can list repositories in the UI and + create or refresh the `OpenHands Resolver` repository webhook. OpenHands does + not perform other repository administration actions. + + +![Bitbucket Data Center incoming OAuth link form](../images/bitbucket-data-center-incoming-link.png) + +## Create a Bot Token + +This step is strongly recommended but technically optional. When a bot token is +configured, OpenHands posts comments and reactions as the bot account instead of +as the user. + +Create a dedicated Bitbucket Data Center user for OpenHands. For example, create +a user named `openhands` with an email address such as +`openhands-bot@company.com`. Grant this user access to all repositories where +OpenHands should post comments or reactions. Then create an HTTP access token +for that user with **Repository permissions** set to **Repository write**. Store +the token securely. You will need to paste the HTTP access token into the +OpenHands Enterprise Admin Console. + +![Bitbucket Data Center HTTP access token setup](../images/bitbucket-data-center-bot-token.png) + +## Configure the Admin Console + +Open the Replicated Admin Console for your OpenHands Enterprise installation and +go to the application configuration page. + +In **Bitbucket Data Center Authentication**: + +1. Enable **Bitbucket Data Center Authentication**. +2. Enter the **Bitbucket Data Center Domain**. +3. Enter the **Bitbucket Data Center Client ID**. +4. Enter the **Bitbucket Data Center Client Secret**. +5. Enter the **Bitbucket Data Center Bot Token** if you have one. +6. Save and deploy the updated configuration. + + + The Bitbucket Data Center Domain must be a bare hostname, for example + `bitbucket.example.com`. Do not include `https://`. + + +## Sign In with Bitbucket Data Center + +After the deployment is completed, users choose **Sign in with Bitbucket Data +Center** on your app's login page. + +On first sign-in, users may be asked to accept OpenHands terms and complete an +offline access flow. After sign-in, OpenHands stores the user's Bitbucket Data +Center token so it can list repositories and run resolver jobs as that user. + +## Install Repository Webhooks + +To trigger OpenHands on Bitbucket repositories, repository administrators can +install the OpenHands bot onto a repository from **Settings > Integrations** +within the OpenHands app. For each repository that should support `@openhands` +pull request comments, click **Install**. If a webhook already exists, click +**Reinstall** to refresh it. + +OpenHands creates or updates a repository webhook named `OpenHands Resolver`. +The webhook URL is connection-specific: + +```text +https://app./integration/bitbucket-dc/connections//events +``` + +OpenHands subscribes the webhook to repository and pull request events, +including pull request comment add, edit, and delete events. The signing secret +is generated and stored by OpenHands. + +## Trigger OpenHands from Bitbucket Data Center + +Open a pull request and add a comment containing `@openhands`. Inline pull +request comments are also supported. + +OpenHands starts a resolver job when: + +- The repository webhook is installed and active. +- The webhook delivery signature is valid. +- The mentioning Bitbucket user has signed in to OpenHands with Bitbucket Data + Center. +- The mentioning user has access to the repository. + +The resolver context includes the pull request title, description, current +comments, and the triggering comment. OpenHands replies back to the pull request +when the job starts and when it completes. + +## Troubleshooting + +| Symptom | Check | +| --- | --- | +| The Bitbucket Data Center login option is not visible | Confirm Bitbucket Data Center Authentication is enabled in the Admin Console and the deployment has been applied. | +| OAuth redirects fail | Confirm the callback URL exactly matches `https://auth.app./realms/allhands/broker/bitbucket_data_center/endpoint`. | +| Login tries to reach an invalid `https://https://...` URL | Remove `https://` from the Bitbucket Data Center Domain field in the Admin Console. | +| Repository webhook install fails | Confirm the user has repository admin access and the OAuth app grants `REPO_ADMIN`. | +| Webhook delivery reaches OpenHands but no job starts | Confirm the comment contains `@openhands`, the webhook is installed for that repository, and the mentioning Bitbucket user has signed in to OpenHands. | +| OpenHands cannot list Bitbucket repositories or install webhooks | Confirm the OpenHands cluster can reach the Bitbucket Data Center URL. | +| Bitbucket webhook deliveries do not reach OpenHands | Confirm the Bitbucket Data Center network can reach the OpenHands app URL. | +| Bitbucket API calls fail with TLS errors | Upload the Bitbucket Data Center CA certificate in **Additional Trusted CA Certificates** and redeploy. | diff --git a/enterprise/integrations/jira-data-center.mdx b/enterprise/integrations/jira-data-center.mdx new file mode 100644 index 00000000..5bd2e035 --- /dev/null +++ b/enterprise/integrations/jira-data-center.mdx @@ -0,0 +1,236 @@ +--- +title: Jira Data Center +description: Configure Jira Data Center for OpenHands Enterprise. +icon: building +--- + +This guide explains how to connect Jira Data Center 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. + +![Jira Data Center issue with OpenHands comments](../images/jira-data-center-openhands-comment.png) + +## Prerequisites + +- Jira Data Center administrator access to create users, personal access + tokens, OAuth applications, and webhooks. +- Jira Data Center with OAuth 2.0 incoming application links enabled. If you do + not see **External application** and **Incoming** while creating the link, + verify your Jira Data Center version and application link settings. +- Network access from OpenHands to Jira Data Center for API calls, and from + Jira Data Center back to the OpenHands app URL for webhook delivery. +- If Jira Data Center uses an internal or self-signed certificate, upload the + issuing CA in the OpenHands Enterprise Admin Console under **Additional + Trusted CA Certificates** before deploying. + + + Jira Data Center setup is global for the OpenHands Enterprise installation. + Service account values are configured in the Admin Console. Webhook setup is + completed later inside OpenHands. + + +## Create a Bot Token + +Create a dedicated Jira user for OpenHands. For example, create a user named +`openhands` with an email address such as `openhands-bot@company.com`. +OpenHands uses this bot account to read issues, add comments, and add +reactions. Grant it access to all Jira projects where OpenHands should read and +comment. + +After you have granted the bot user access, sign in as the `openhands` user and +create a Jira personal access token from the user's profile. Store it securely. +You will need to paste the bot account email and PAT into the OpenHands +Enterprise Admin Console. + +![Jira Data Center personal access token permissions inherit the user's access](../images/jira-data-center-personal-access-token-permissions.png) + +## Create a Jira OAuth Application + +OAuth linking is recommended because it lets team members prove ownership of +their Jira account before using OpenHands to process their Jira events. + +In Jira Data Center, open **Administration > Applications > Application links** +and create a new link. When Jira asks what type of application to connect, +choose **External application**. For the direction, choose **Incoming** because +OpenHands connects to Jira during OAuth linking. + +![Jira Data Center create incoming OAuth link dialog](../images/jira-data-center-create-incoming-link.png) + +Configure the incoming link with this callback URL: + +```text +https://app./integration/jira-dc/callback +``` + +Use your actual app hostname, for example: + +```text +https://app.openhands.example.com/integration/jira-dc/callback +``` + +When prompted for OAuth scopes, select `WRITE`. + +![Jira Data Center incoming OAuth link form](../images/jira-data-center-incoming-link-form.png) + +Copy the OAuth client ID and client secret and store them securely. You will +paste them into the Admin Console. + +![Jira Data Center OAuth credentials](../images/jira-data-center-oauth-credentials.png) + + + If your Jira Data Center installation cannot provide an OAuth application, you + can select email matching in the Admin Console instead. In that mode, + OpenHands links Jira users by matching their Jira email address to their + OpenHands email address. + + +## Configure the Admin Console + +Open the Replicated Admin Console for your OpenHands Enterprise installation and +go to the application configuration page. + +In **Jira Data Center Integration**: + +1. Enable **Jira Data Center Integration**. +2. Select the user linking method: + - **OAuth** is recommended. + - **Email match** can be used if OAuth is not available. +3. Enter the **Jira Data Center Service Account Email**. +4. Enter the **Jira Data Center Service Account PAT**. +5. If using OAuth, enter the **Jira Data Center Base URL**, including + `https://`. +6. If using OAuth, enter the **Jira Data Center OAuth Client ID** and + **OAuth Client Secret**. +7. Save and deploy the updated configuration. + + + The Jira Data Center Base URL must include the scheme, for example + `https://jira.example.com`. Do not enter only `jira.example.com`. + + +## Install the Jira Webhook + +After OpenHands is deployed, sign in to OpenHands and open +**Settings > Integrations > Jira Data Center**. + +If OAuth is enabled, click **Connect** and complete the Jira OAuth flow. Then set +up the webhook using one of the options below. + +### Automatic setup + +Choose **Install automatically** and paste a short-lived Jira admin PAT. +OpenHands uses this PAT once to call Jira's webhook API and then discards it. The +PAT is never stored. The automatic setup creates or updates a Jira global +webhook named `OpenHands` that points to this OpenHands URL. + +```text +https://app./integration/jira-dc/connections//events +``` + +### Manual setup + +Choose **Set it up in Jira myself**, then click **Generate webhook details**. +OpenHands saves the connection and shows a webhook URL and signing secret. + +![Jira Data Center manual webhook setup values](../images/jira-data-center-manual-webhook.png) + +Automatic setup is recommended. If you choose manual setup, OpenHands still +requires Jira to sign deliveries. Jira stores that value in the webhook +`configuration.SECRET` property used by the `/rest/jira-webhook/1.0/webhooks` +API. If your Jira admin UI does not expose that advanced configuration, create +or update the webhook with the Jira webhook REST API instead. + +Use these events: + +- `jira:issue_created` +- `jira:issue_updated` +- `jira:issue_deleted` +- `comment_created` +- `comment_updated` +- `comment_deleted` + + + +```bash +curl -X POST 'https://jira.example.com/rest/jira-webhook/1.0/webhooks' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + --data '{ + "name": "OpenHands", + "url": "", + "events": [ + "jira:issue_created", + "jira:issue_updated", + "jira:issue_deleted", + "comment_created", + "comment_updated", + "comment_deleted" + ], + "active": true, + "scopeType": "global", + "configuration": { + "SECRET": "", + "EXCLUDE_BODY": "false" + } + }' +``` + + + +After saving the webhook in Jira, return to OpenHands and click +**I created the webhook**. + +## Link Users + +Each user who wants to invoke OpenHands from Jira should sign in to OpenHands and +connect their Jira Data Center account from **Settings > Integrations > Jira Data +Center**. + + + Webhook setup is global for the OpenHands Enterprise installation. Only the + user setting up the integration needs to install the webhook or provide a Jira + admin PAT. Other teammates only need to connect their own Jira Data Center + account from **Settings > Integrations** before using `@openhands` from Jira. + + +When a Jira event arrives, OpenHands resolves the Jira user to an OpenHands user. +If the Jira user has an OpenHands account but has not connected Jira Data +Center, OpenHands comments on the issue asking them to connect their account and +try again. +If no OpenHands account exists for the Jira user's email address, OpenHands +comments on the issue asking the user to sign up and try again. + +## Trigger OpenHands from Jira + +Create or update a Jira issue with clear requirements. Include the target +repository in the issue description or in a follow-up comment, for example: + +```text +Repository: Acme/web-app +``` + +OpenHands looks for a line starting with `Repository:` followed by the +`org/repo` slug. + +Then trigger OpenHands with either: + +- A Jira comment containing `@openhands`. +- The `openhands` label on the issue. + +The invoking OpenHands user must have access to the target repository written in +the Jira issue. If OpenHands cannot determine or access the repository, it +comments on the issue with the next step to fix the repository reference or +access. + +## Troubleshooting + +| Symptom | Check | +| --- | --- | +| The Jira Data Center card is not visible in OpenHands | Confirm Jira Data Center Integration is enabled in the Admin Console and the deployment has been applied. | +| OAuth redirects fail | Confirm the Jira OAuth callback URL exactly matches `https://app./integration/jira-dc/callback`. | +| Automatic webhook setup fails | Confirm the admin PAT belongs to a Jira user allowed to create global webhooks. | +| Webhook deliveries return `403` | Confirm the webhook URL and signing secret match the values generated by OpenHands. | +| Webhook deliveries reach OpenHands but no job starts | Confirm the Jira user is linked, the integration is active, the comment contains `@openhands` or the issue update added the `openhands` label, and the user has access to the repository. | +| OAuth, issue reads, or automatic webhook setup fail with connection errors | Confirm the OpenHands cluster can reach the Jira Data Center URL. | +| Jira webhook deliveries do not reach OpenHands | Confirm the Jira Data Center network can reach the OpenHands app URL. | +| Jira API calls fail with TLS errors | Upload the Jira Data Center CA certificate in **Additional Trusted CA Certificates** and redeploy. | diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index 8e24b39c..f0286f76 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -6,7 +6,7 @@ icon: rocket This guide walks you through trialing OpenHands Enterprise on your own infrastructure. You'll provision infrastructure (AWS Terraform or a manual VM setup), configure -GitHub for user authentication, and set up Anthropic as your LLM provider. +GitHub for user authentication, and configure your LLM provider. ## Who This Is For @@ -26,7 +26,8 @@ Before you begin, make sure you have the following ready: Sign up for a free 30-day OpenHands Enterprise trial account. You'll need this to access the installer dashboard. -- **Anthropic API key** from the [Anthropic Console](https://console.anthropic.com/) +- **LLM credentials** from your chosen provider, for example an Anthropic API + key from the [Anthropic Console](https://console.anthropic.com/) - **A GitHub account** with permission to create GitHub Apps - **An AWS account** with permissions to create EC2, VPC, and Route53 resources (**if using the AWS with Terraform path**) @@ -335,7 +336,13 @@ You should now see the application configuration page. ### LLM Configuration -Enter your Anthropic API key from the [Anthropic Console](https://console.anthropic.com/). +Choose an LLM provider from the LLM Configuration dropdown and enter the details +from that provider. + +![LLM Configuration provider dropdown](./images/llm-configuration-provider-dropdown.png) + +For example, if you use Anthropic, enter your API key from the +[Anthropic Console](https://console.anthropic.com/). ### Database Configuration @@ -359,6 +366,21 @@ Go back to the Installer Admin Console in your browser and enter the values from After filling in all fields, click **Continue** at the bottom of the page. +### Additional Integrations + +If your team uses Jira Data Center or Bitbucket Data Center, follow these guides +to configure Admin Console values before deployment and complete webhook setup +inside OpenHands after deployment. + + + + Configure Bitbucket Data Center login, repository access, bot identity, and pull request webhooks. + + + Configure Jira issue triggers, OAuth account linking, service account credentials, and Jira webhooks. + + + ## Deploy and Verify OpenHands will begin deploying. You can expect the deployment status to transition from