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.