From 39e39b3a7fe696724c0f15827b57c9e4304c851d Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Mon, 21 Sep 2026 17:14:33 -0500 Subject: [PATCH] docs: explain GitHub service account identity for conversations --- enterprise/conversations-and-sandboxes.mdx | 4 ++ enterprise/integrations/github.mdx | 44 ++++++++++++++++++++ llms-full.txt | 48 ++++++++++++++++++++++ 3 files changed, 96 insertions(+) diff --git a/enterprise/conversations-and-sandboxes.mdx b/enterprise/conversations-and-sandboxes.mdx index 109ed56e..c1a2718b 100644 --- a/enterprise/conversations-and-sandboxes.mdx +++ b/enterprise/conversations-and-sandboxes.mdx @@ -210,6 +210,10 @@ when a plugin requires a conversation-specific credential. separately because the push credential does not set commit authorship. +For a complete service account workflow, including the difference between the +PAT's permissions and the identity recorded in commits, see +[Use a Service Account for Automated Conversations](/enterprise/integrations/github#use-a-service-account-for-automated-conversations). + For tested implementations, see the [per-conversation secrets](https://github.com/jpshackelford/oh-examples/tree/main/per-conversation-secrets) and diff --git a/enterprise/integrations/github.mdx b/enterprise/integrations/github.mdx index 5085125e..9de67ed8 100644 --- a/enterprise/integrations/github.mdx +++ b/enterprise/integrations/github.mdx @@ -32,6 +32,9 @@ The integration uses two GitHub identities: This is why an `I'm on it!` comment can appear as the bot while the resulting pull request review appears as the user who requested it. +If automated work must use a dedicated GitHub identity, see +[Use a Service Account for Automated Conversations](#use-a-service-account-for-automated-conversations). + ## Prerequisites Before you start, confirm: @@ -280,6 +283,47 @@ GitHub App bot. If your organization requires reviews to have a machine identity use an [OpenHands code review automation](/openhands/usage/use-cases/code-review#option-b-openhands-automation-org-wide) with a dedicated bot credential. +### Use a Service Account for Automated Conversations + +For API-started conversations, a GitHub service account can own repository +operations while a person signs in to OpenHands with GitHub or a SAML provider +such as [Authentik](/enterprise/integrations/saml-providers/authentik). This is +separate from the built-in `@openhands` resolver, which uses the triggering +user's GitHub authorization for repository operations. + +1. Create a dedicated GitHub account and grant it access to the repositories + and actions the automation needs. +2. Create a narrowly scoped PAT for that account. Pass it as `GITHUB_TOKEN` in + the `secrets` map when calling `POST /api/v1/app-conversations`. Do not put + the token in the initial message. See + [Pass Secrets At Conversation Start](/enterprise/conversations-and-sandboxes#pass-secrets-at-conversation-start). +3. If the PAT belongs to a different GitHub user than the OpenHands account, + omit `selected_repository` from the start request. Clone the repository + after startup, or prepare a sandbox and attach the conversation. +4. Set the Git name and email used for commits. The PAT authorizes repository + operations but does not set commit authorship. Use an email associated with + the service account so GitHub attributes its commits to that account. + +`Settings > Application > Git Settings` saves the Git name and email for the +OpenHands user who starts the conversation. OpenHands applies these settings +when preparing the sandbox, whether or not a repository was selected at +startup. If only one repository should use the service account's commit +identity, run these commands in that repository instead: + +```bash +git config user.name "OpenHands Bot" +git config user.email "bot@example.com" +``` + +Replace the example email with one associated with the service account. + + + A service account PAT authenticates as a GitHub user. It is not a GitHub App + installation token. The GitHub App configured earlier in this guide handles + integration events and bot status comments; it does not make the built-in + resolver perform repository operations as the app bot. + + ### Completion Comments The built-in resolver posts the agent's final response as a completion comment. diff --git a/llms-full.txt b/llms-full.txt index f6ba8a4a..5cc4a5a9 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -48555,6 +48555,10 @@ when a plugin requires a conversation-specific credential. separately because the push credential does not set commit authorship. +For a complete service account workflow, including the difference between the +PAT's permissions and the identity recorded in commits, see +[Use a Service Account for Automated Conversations](/enterprise/integrations/github#use-a-service-account-for-automated-conversations). + For tested implementations, see the [per-conversation secrets](https://github.com/jpshackelford/oh-examples/tree/main/per-conversation-secrets) and @@ -50628,6 +50632,9 @@ The integration uses two GitHub identities: This is why an `I'm on it!` comment can appear as the bot while the resulting pull request review appears as the user who requested it. +If automated work must use a dedicated GitHub identity, see +[Use a Service Account for Automated Conversations](#use-a-service-account-for-automated-conversations). + ## Prerequisites Before you start, confirm: @@ -50876,6 +50883,47 @@ GitHub App bot. If your organization requires reviews to have a machine identity use an [OpenHands code review automation](/openhands/usage/use-cases/code-review#option-b-openhands-automation-org-wide) with a dedicated bot credential. +### Use a Service Account for Automated Conversations + +For API-started conversations, a GitHub service account can own repository +operations while a person signs in to OpenHands with GitHub or a SAML provider +such as [Authentik](/enterprise/integrations/saml-providers/authentik). This is +separate from the built-in `@openhands` resolver, which uses the triggering +user's GitHub authorization for repository operations. + +1. Create a dedicated GitHub account and grant it access to the repositories + and actions the automation needs. +2. Create a narrowly scoped PAT for that account. Pass it as `GITHUB_TOKEN` in + the `secrets` map when calling `POST /api/v1/app-conversations`. Do not put + the token in the initial message. See + [Pass Secrets At Conversation Start](/enterprise/conversations-and-sandboxes#pass-secrets-at-conversation-start). +3. If the PAT belongs to a different GitHub user than the OpenHands account, + omit `selected_repository` from the start request. Clone the repository + after startup, or prepare a sandbox and attach the conversation. +4. Set the Git name and email used for commits. The PAT authorizes repository + operations but does not set commit authorship. Use an email associated with + the service account so GitHub attributes its commits to that account. + +`Settings > Application > Git Settings` saves the Git name and email for the +OpenHands user who starts the conversation. OpenHands applies these settings +when preparing the sandbox, whether or not a repository was selected at +startup. If only one repository should use the service account's commit +identity, run these commands in that repository instead: + +```bash +git config user.name "OpenHands Bot" +git config user.email "bot@example.com" +``` + +Replace the example email with one associated with the service account. + + + A service account PAT authenticates as a GitHub user. It is not a GitHub App + installation token. The GitHub App configured earlier in this guide handles + integration events and bot status comments; it does not make the built-in + resolver perform repository operations as the app bot. + + ### Completion Comments The built-in resolver posts the agent's final response as a completion comment.