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/analytics.mdx b/enterprise/analytics.mdx index 8fd45f0c..e1b84608 100644 --- a/enterprise/analytics.mdx +++ b/enterprise/analytics.mdx @@ -71,7 +71,7 @@ Once a project has been created, Laminar is ready to listen for traces. Important: Always use ingest API keys when deploying. -Create a key with ther right permissions. Ingest only keys are recommended as they only have write access to write traces. They cannot be used to read data. +Create a key with the right permissions. Ingest only keys are recommended as they only have write access to write traces. They cannot be used to read data. ![Configure Laminar Ingest Only Key](./images/laminar-ingest-only-key.png) 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..95295f74 --- /dev/null +++ b/enterprise/integrations/bitbucket-data-center.mdx @@ -0,0 +1,155 @@ +--- +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. +- A currently supported Bitbucket Data Center version 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 +``` + +Replace only `` in the callback URL. Leave the rest of +the path unchanged. + +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..c3bc79e9 --- /dev/null +++ b/enterprise/integrations/jira-data-center.mdx @@ -0,0 +1,209 @@ +--- +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. +- A currently supported Jira Data Center version 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` (allows OpenHands to link Jira +accounts and make Jira API calls within the user's granted Jira permissions). + +![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, create a global +webhook using the generated URL and signing secret. Jira must include the +request body and sign deliveries with the generated secret; if your Jira admin +UI does not support those settings, use automatic setup. + +Use these events: + +- `jira:issue_created` +- `jira:issue_updated` +- `jira:issue_deleted` +- `comment_created` +- `comment_updated` +- `comment_deleted` + +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 same +`org/repo` format configured in your connected source control provider. + +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..cf686e4b 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 @@ -357,6 +364,21 @@ Run our [script](https://github.com/All-Hands-AI/OpenHands-Cloud/tree/main/scrip Go back to the Installer Admin Console in your browser and enter the values from the Create GitHub App script output. For the private key, upload the file from the `keys` directory of the script location. +### 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. + + + After filling in all fields, click **Continue** at the bottom of the page. ## Deploy and Verify diff --git a/openhands/usage/use-cases/spark-migrations.mdx b/openhands/usage/use-cases/spark-migrations.mdx index 14cf6247..19be47c0 100644 --- a/openhands/usage/use-cases/spark-migrations.mdx +++ b/openhands/usage/use-cases/spark-migrations.mdx @@ -31,7 +31,7 @@ In this document, we will explore how OpenHands contributes to Spark migrations, ## Understanding -Before changin any code, it helps to build a clear picture of what is affected and where the risk is concentrated. Spark migrations touch a large surface area, between API deprecations, behavioral changes, configuration defaults, and dependency versions, and the interactions between them are hard to reason about manually. +Before changing any code, it helps to build a clear picture of what is affected and where the risk is concentrated. Spark migrations touch a large surface area, between API deprecations, behavioral changes, configuration defaults, and dependency versions, and the interactions between them are hard to reason about manually. Apache releases detailed lists of changes between each major and minor version of Spark. OpenHands can utilize this list of changes while scanning your codebase to produce a structured inventory of everything that needs attention. This inventory becomes the foundation for the migration itself, helping you prioritize work and track progress.