docs: explain GitHub service account identity for conversations

enterprise/conversations-and-sandboxes.mdx

@@ -144,7 +144,7 @@
 | --- | --- | --- |
 | `observability_span_name` | string | Creates a named child span under the root `conversation` span. Use stable, low-cardinality names for grouping and signal routing. |
 | `observability_tags` | string array | Adds tags to the conversation root observability span. |
 | `observability_metadata` | object | Adds trace-level metadata. Values must be scalars or homogeneous scalar arrays, such as strings, numbers, booleans, `string[]`, `number[]`, or `boolean[]`. |
 
 ```json
 {
@@ -158,10 +158,10 @@
     ],
     "run": true
   },
   "selected_repository": "yourorganization/yourrepository",
   "observability_span_name": "wb_rubric_eval",
   "observability_tags": ["wb-rubric", "evaluation"],
   "observability_metadata": {
     "evaluation": "wb",
     "attempt": 1,
     "replay": false
@@ -210,6 +210,10 @@
   separately because the push credential does not set commit authorship.
 </Warning>
 
+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

enterprise/integrations/github.mdx

@@ -32,14 +32,17 @@
 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:
 
 - OpenHands Enterprise is reachable at `https://app.<your-base-domain>`.
 - The authentication service is reachable at `https://auth.<your-base-domain>`
   when using the default **Simple** hostname mode.
 - Both hostnames use publicly trusted TLS certificates.
 - You can create a GitHub App for your user or organization.
 - You can install the app on the organizations and repositories that should use OpenHands.
 - Your workstation has [uv](https://docs.astral.sh/uv/) and can open a browser to GitHub.
@@ -66,7 +69,7 @@
 ```
 
 Pass `--org <github-org>` to create the app under a GitHub organization instead
 of your personal account. If the installation uses the **Legacy** hostname mode,
 also pass `--dns-layout nested` so the OAuth callback uses
 `auth.app.<your-base-domain>` instead of `auth.<your-base-domain>`.
 
@@ -98,7 +101,7 @@
 | OAuth callback URL | `https://auth.<your-base-domain>/realms/allhands/broker/github/endpoint` |
 | Webhook URL | `https://app.<your-base-domain>/integration/github/events` |
 
 The OAuth callback URL above is for the default **Simple** hostname mode. The
 helper uses `auth.app.<your-base-domain>` when run with `--dns-layout nested` for
 the **Legacy** mode. The OAuth callback handles user sign-in, while the webhook
 URL receives issue and pull request events; these URLs are not interchangeable.
@@ -188,7 +191,7 @@
 5. Posts the conversation's final response as a completion comment from the GitHub App.
 
 The acknowledgement and completion comment are part of the built-in resolver.
 They are not custom event automations.
 
 ## Customize Resolver Conversations
 
@@ -203,7 +206,7 @@
 relevant to the task.
 
 By default, GitHub resolver conversations automatically receive the built-in
 GitHub skill. The resolver's initial message refers to GitHub APIs, which matches
 the skill's `github` trigger. This gives the agent the baseline instructions for
 using GitHub, but it does not limit the conversation to that skill. Repository,
 organization, and other task-specific skills can apply alongside it. For example,
@@ -280,6 +283,47 @@
 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.
+
+<Note>
+  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.
+</Note>
+
 ### Completion Comments
 
 The built-in resolver posts the agent's final response as a completion comment.
@@ -288,7 +332,7 @@
 
 A repository or organization skill can reduce duplication by telling the agent
 to keep its final response brief and refer readers to the formal review. A skill
 cannot disable the resolver's completion callback itself.
 
 ## Troubleshooting
 

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.
 </Warning>
 
+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.
+
+<Note>
+  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.
+</Note>
+
 ### Completion Comments
 
 The built-in resolver posts the agent's final response as a completion comment.