From 45dd718aa5da069409f3bc06255610930042f913 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 18 Nov 2026 08:49:42 +0000 Subject: [PATCH 01/10] docs/abc: Document collaboration roles and whose credentials each action uses --- docs/admin/access-control/batch-changes.mdx | 14 +-- docs/agentic-batch-changes/collaboration.mdx | 100 +++++++++++++++++++ docs/agentic-batch-changes/configuration.mdx | 2 + docs/agentic-batch-changes/index.mdx | 2 +- src/data/navigation.ts | 4 + 5 files changed, 114 insertions(+), 8 deletions(-) create mode 100644 docs/agentic-batch-changes/collaboration.mdx diff --git a/docs/admin/access-control/batch-changes.mdx b/docs/admin/access-control/batch-changes.mdx index ef78a1fe3..6d26b4d39 100644 --- a/docs/admin/access-control/batch-changes.mdx +++ b/docs/admin/access-control/batch-changes.mdx @@ -2,13 +2,13 @@ Granular controls for who can access [Batch Changes](/batch-changes/) can be configured by administrators by tuning the roles assigned to users and the permissions granted to those roles. This page describes the permission types available for Batch Changes, and whether they are granted by default to the **User** [system role](/admin/access-control#system-roles). All permissions are granted to the **Administrator** system role by default. -| Name | Description | Granted to **User** by default? | -| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-----------------------------: | -| `batch_changes:read` | | ✓ | -| `batch_changes:write` | | ✓ | -| `batch_changes:agent_read` | | ✓ | -| `batch_changes:agent_write` | | ✓ | -| `batch_change_agent_administration:manage` | | | +| Name | Description | Granted to **User** by default? | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-----------------------------: | +| `batch_changes:read` | | ✓ | +| `batch_changes:write` | | ✓ | +| `batch_changes:agent_read` | | ✓ | +| `batch_changes:agent_write` | | ✓ | +| `batch_change_agent_administration:manage` | | | These permissions gate access to the Batch Changes feature as a whole. Within a batch change, what a user can see and do is further limited by the batch change's [permission levels](/batch-changes/permissions-in-batch-changes#permission-levels-for-batch-changes) and by their [repository permissions](/batch-changes/permissions-in-batch-changes#repository-permissions-for-batch-changes). Merging changesets can additionally be restricted to administrators with the `batchChanges.restrictMergeToAdmins` [advanced configuration](/batch-changes/permissions-in-batch-changes#restricting-merges-to-site-admins) property. diff --git a/docs/agentic-batch-changes/collaboration.mdx b/docs/agentic-batch-changes/collaboration.mdx new file mode 100644 index 000000000..8006a5737 --- /dev/null +++ b/docs/agentic-batch-changes/collaboration.mdx @@ -0,0 +1,100 @@ +# Collaboration + + + Collaboration is experimental and available only on [Sourcegraph + Cloud](/cloud). It is behind the `abc-collaboration` feature flag. To turn + it on for your instance, contact Sourcegraph. + + +Collaboration lets the owner of an agentic batch change invite other users to work on it. A collaborator can talk to the agent, answer its questions, run workspaces, and publish, for a fixed time. For example, a platform engineer who owns a framework migration invites a service team member for 24 hours to answer the agent's questions about that team's repositories and fix their CI failures. + +Each action runs as the user who does it, not as the owner. See [Whose credentials an action uses](#whose-credentials-an-action-uses). + +## Roles + +- **Owner**: the user who created the agent, or who got it through a [handover](/agentic-batch-changes/configuration#handing-over-an-agent). There is one owner. The owner can do everything a collaborator can do, and also: + - Invite, extend, and remove collaborators. + - Approve publications. + - Hand over the agent. + - Rename, share, stop, and delete the agent, and start new threads. + - Close, move, and delete the batch change. +- **Collaborator**: a user the owner invited. A collaborator sees the full transcript and the list of collaborators, and can: + - Send messages and upload files. + - Answer the agent's questions and approve tool calls, except publication approvals. + - Cancel and retry turns. + - Run workspaces, publish, and clean up changesets that the current plan no longer produces. + - Act on changesets on the batch change page: publish, push the branch, comment, close, merge, rebase, sync, and retry. +- **Administrator** with the `BATCH_CHANGE_AGENT_ADMINISTRATION#MANAGE` [permission](/admin/access-control/batch-changes): sees every agent on the [Threads page](/agentic-batch-changes/configuration#threads-page), can hand over any agent, and can invite, extend, and remove collaborators. An administrator who is not a collaborator cannot send messages or act on the agent. +- **Previous owner**: after a handover, the previous owner keeps read access to the agent. This access does not expire, and the previous owner cannot act on the agent. +- **Viewer**: a user who opens the agent through its [share link](/agentic-batch-changes/configuration#sharing-and-visibility). A viewer can read the transcript but cannot act on the agent or see the collaborator list. + +## Inviting collaborators + +The owner or an administrator invites collaborators from the collaborators panel on the agent page. To be invited, a user must: + +- Be a user on the instance other than the owner. +- Have the `Batch Changes: Write` and `Batch Changes: Agent Write` [permissions](/agentic-batch-changes/configuration#access). Sourcegraph refuses the invite otherwise. + +Sourcegraph does not check the collaborator's repository permissions when they are invited. The collaborator's own repository permissions apply when they act. See [Whose credentials an action uses](#whose-credentials-an-action-uses). + +Every collaborator access expires. Select 1 hour, 24 hours, or 7 days when you invite. There is no access without an expiry and no limit on the number of collaborators. The invited user gets a notification in Sourcegraph, and the access starts immediately. + +To extend access, select a new duration. The access then ends that long from now, not from the old end time. After access expires or is removed, invite the user again. + +A collaborator cannot leave an agent. Access ends when it expires or when the owner or an administrator removes it. Removing a user's `Batch Changes: Agent Write` permission also stops them from acting on the agent. + +The [audit log](/agentic-batch-changes/configuration#audit-log) records `collaboratorInvited`, `collaboratorExtended`, and `collaboratorRevoked` with the owner, the collaborator, the user who made the change, and the expiry. Conversation and workspace actions record both the owner and the user who acted. + +## Whose credentials an action uses + +The user who sends the message, answers the question, approves the tool call, or clicks the action is the user it runs as. That user's repository permissions, Batch Changes credentials, secrets, connectors, guidance, and usage limits apply: + +- The agent researches and runs Deep Search as that user. Repository names the agent sees are limited to repositories that both the owner and that user can read. +- Guidance and skills come from that user's settings and from the site and organization settings that apply to them. +- Workspaces and coding agent steps run as that user, with that user's secrets, connectors, and Sourcegraph MCP identity. Coding agent step runs count against that user's [usage limits](/agentic-batch-changes/configuration#usage-limits). +- Tool approvals belong to the user who gave them. An approval from one user does not count for a turn that runs as another user, also when the approval was for this agent or for all agents. + +When an action cannot run as that user, it is refused with a reason. It does not fall back to the owner. For example, a publish is refused when the user has no valid Batch Changes credential for a code host and there is no global credential, and a workspace fails when a secret it needs is not available to that user. + +### Exceptions + +In these cases, the user an action runs as or is charged to is not the user who wrote the message: + +- **Automatic turns**: when the agent wakes up on its own, for example after a run finishes or CI reports a result, the turn runs as the current owner. +- **Changeset hooks**: CI and merge conflict automations run as the user whose turn prepared the current plan. When a collaborator's turn prepared it, hooks use that collaborator's permissions, secrets, and connectors. +- **Retry**: a retried turn runs as the user who clicks **Retry**, not as the author of the original message. +- **Answers and approvals**: when a turn is waiting for an answer or an approval, any owner or collaborator can answer. The turn then continues as the user who answered. +- **Publication approvals**: only the owner can approve a publication. A collaborator can publish only to repositories and in a mode, such as draft, that the owner already approved for this agent. +- **Code host pushes and syncs**: Sourcegraph pushes and syncs all changesets of the batch change with the Batch Changes credential of the user who last applied it, or the global credential when that user has none. This also applies to changesets that another user published. Publishing from the conversation makes the publishing user the last applier. Publishing from the batch change page does not change the last applier, so the push uses the credential of the previous last applier. Comment, close, merge, and rebase use the credential of the user who starts them. +- **Published changesets entitlement**: when a collaborator publishes, the published changeset counts against the collaborator's entitlement. When the owner publishes, it counts against the owner's. +- **Billing**: merged changesets are [billed](/agentic-batch-changes/configuration#billing) to the subscription and recorded for the owner, no matter who published or merged them. +- **Batch change namespace**: the batch change stays in the owner's namespace, also when a collaborator's turn creates or updates it. +- **Uploaded files**: files are stored with the agent under the owner, no matter who uploaded them. Every user who can open the agent can download them. +- **Repository visibility at publish**: Sourcegraph checks that the owner can read the target repositories before it publishes, in addition to the publishing user's own permissions. + +## When access ends + +When a collaborator's access expires or is removed: + +- A turn of theirs that has not started yet fails with a message that the author no longer has write access. The owner or another collaborator can retry it. The retry runs as the user who retries. +- A turn of theirs that is running is not stopped. The agent can continue to read and research, but it cannot run workspaces, publish, prune, or merge as that user. +- Questions and approvals that wait in their turn stay open. The owner or another collaborator can answer them, and the turn continues as that user. +- Their approvals for secrets stay saved but apply only to their own turns. + +## Handovers + +A [handover](/agentic-batch-changes/configuration#handing-over-an-agent) needs the agent to be idle or waiting for input, so no turn is running or queued at that time. During a handover: + +- Collaborators keep their access, except the new owner, who becomes the owner. +- The previous owner keeps read access. +- All publication approvals are removed. The new owner approves publications again. +- Questions and approvals that wait stay open. The new owner or a collaborator can answer them, and the turn continues as that user. + +## Turning collaboration off + +When Sourcegraph turns off the `abc-collaboration` flag: + +- The collaborators panel is hidden, also for the owner. +- Collaborators can still open the agent and read the transcript, but they cannot send messages, answer questions, approve tool calls, cancel or retry turns, or act on changesets on the batch change page. +- Collaborator access is kept. If the flag is turned on again, access that has not expired works again. +- A turn that a collaborator started before the flag was turned off continues. diff --git a/docs/agentic-batch-changes/configuration.mdx b/docs/agentic-batch-changes/configuration.mdx index d4e68927c..5c4c44b8f 100644 --- a/docs/agentic-batch-changes/configuration.mdx +++ b/docs/agentic-batch-changes/configuration.mdx @@ -130,6 +130,8 @@ Both halves of a pair are required. All four are part of the built-in User role, Each agentic batch change has one owner: the user who created it, until it is [handed over](#handing-over-an-agent). Only the owner can send messages, approve actions, run workspaces, and publish. Other users can read the conversation, the plan, and the results, but they cannot change anything; see [Sharing and visibility](#sharing-and-visibility). There is no co-ownership. Because the agent acts as its owner, the owner's repository permissions and Batch Changes credentials bound what it can touch. +On Sourcegraph Cloud, the owner can invite collaborators who act on the agent with their own credentials. This is experimental. See [Collaboration](/agentic-batch-changes/collaboration). + ### Handing over an agent A handover makes another user the owner of an agent and its batch change. Use it when the owner leaves the team, is on leave, or when the work moves to someone else. diff --git a/docs/agentic-batch-changes/index.mdx b/docs/agentic-batch-changes/index.mdx index c1aa50010..dcb2681d6 100644 --- a/docs/agentic-batch-changes/index.mdx +++ b/docs/agentic-batch-changes/index.mdx @@ -64,4 +64,4 @@ If everything goes well, the agent might ask if it can continue. By default, the When configured to handle CI failures, the agent fetches the logs, iterates to fix the problem, and updates the changeset. You can step away and ask "what happened while I was away?" when you return for a summary of everything that changed. When reviewers approve and CI is green, merge on the code host or use **Merge** in Sourcegraph's changeset view, where available. The agent cannot merge changesets from the conversation. -To let colleagues follow the work, use **Share** on the agent page. See [Sharing and visibility](/agentic-batch-changes/configuration#sharing-and-visibility). To let a colleague take over the work, use **Share** > **Hand over**. See [Handing over an agent](/agentic-batch-changes/configuration#handing-over-an-agent). +To let colleagues follow the work, use **Share** on the agent page. See [Sharing and visibility](/agentic-batch-changes/configuration#sharing-and-visibility). To let a colleague take over the work, use **Share** > **Hand over**. See [Handing over an agent](/agentic-batch-changes/configuration#handing-over-an-agent). To work on it together with colleagues, invite them as collaborators. See [Collaboration](/agentic-batch-changes/collaboration). diff --git a/src/data/navigation.ts b/src/data/navigation.ts index a4c5efff0..2ecb743b4 100644 --- a/src/data/navigation.ts +++ b/src/data/navigation.ts @@ -39,6 +39,10 @@ export const navigation: NavigationItem[] = [ title: 'Configuration and administration', href: '/agentic-batch-changes/configuration' }, + { + title: 'Collaboration', + href: '/agentic-batch-changes/collaboration' + }, { title: 'Connectors', href: '/agentic-batch-changes/connectors' From 1d44f8f88ed994bf20973051063a9308c7390c11 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 18 Nov 2026 08:50:16 +0000 Subject: [PATCH 02/10] docs/abc: Document that the agent can merge changesets Amp-Thread-ID: https://ampcode.com/threads/T-01a1e4d8-de7d-7217-baa1-3fb2338878a6 --- docs/agentic-batch-changes/collaboration.mdx | 3 ++- docs/agentic-batch-changes/index.mdx | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/agentic-batch-changes/collaboration.mdx b/docs/agentic-batch-changes/collaboration.mdx index 8006a5737..36140fb6f 100644 --- a/docs/agentic-batch-changes/collaboration.mdx +++ b/docs/agentic-batch-changes/collaboration.mdx @@ -23,7 +23,8 @@ Each action runs as the user who does it, not as the owner. See [Whose credentia - Answer the agent's questions and approve tool calls, except publication approvals. - Cancel and retry turns. - Run workspaces, publish, and clean up changesets that the current plan no longer produces. - - Act on changesets on the batch change page: publish, push the branch, comment, close, merge, rebase, sync, and retry. + - Ask the agent to merge changesets, and approve the merge. + - Act on changesets on the batch change page: publish, push the branch, comment, close, merge, rebase, sync, and retry. - **Administrator** with the `BATCH_CHANGE_AGENT_ADMINISTRATION#MANAGE` [permission](/admin/access-control/batch-changes): sees every agent on the [Threads page](/agentic-batch-changes/configuration#threads-page), can hand over any agent, and can invite, extend, and remove collaborators. An administrator who is not a collaborator cannot send messages or act on the agent. - **Previous owner**: after a handover, the previous owner keeps read access to the agent. This access does not expire, and the previous owner cannot act on the agent. - **Viewer**: a user who opens the agent through its [share link](/agentic-batch-changes/configuration#sharing-and-visibility). A viewer can read the transcript but cannot act on the agent or see the collaborator list. diff --git a/docs/agentic-batch-changes/index.mdx b/docs/agentic-batch-changes/index.mdx index dcb2681d6..b8160b5f1 100644 --- a/docs/agentic-batch-changes/index.mdx +++ b/docs/agentic-batch-changes/index.mdx @@ -62,6 +62,6 @@ If everything goes well, the agent might ask if it can continue. By default, the ### Let the agent finish -When configured to handle CI failures, the agent fetches the logs, iterates to fix the problem, and updates the changeset. You can step away and ask "what happened while I was away?" when you return for a summary of everything that changed. When reviewers approve and CI is green, merge on the code host or use **Merge** in Sourcegraph's changeset view, where available. The agent cannot merge changesets from the conversation. +When configured to handle CI failures, the agent fetches the logs, iterates to fix the problem, and updates the changeset. You can step away and ask "what happened while I was away?" when you return for a summary of everything that changed. When reviewers approve and CI is green, merge on the code host, use **Merge** in Sourcegraph's changeset view where available, or ask the agent to merge. The agent shows an approval card before each merge. To let colleagues follow the work, use **Share** on the agent page. See [Sharing and visibility](/agentic-batch-changes/configuration#sharing-and-visibility). To let a colleague take over the work, use **Share** > **Hand over**. See [Handing over an agent](/agentic-batch-changes/configuration#handing-over-an-agent). To work on it together with colleagues, invite them as collaborators. See [Collaboration](/agentic-batch-changes/collaboration). From 9e56f85597740b77ed05d27569bd540eb671d549 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 18 Nov 2026 08:50:36 +0000 Subject: [PATCH 03/10] docs/abc: Fix collaborator list indentation Amp-Thread-ID: https://ampcode.com/threads/T-01a1e4d8-de7d-7217-baa1-3fb2338878a6 --- docs/agentic-batch-changes/collaboration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agentic-batch-changes/collaboration.mdx b/docs/agentic-batch-changes/collaboration.mdx index 36140fb6f..305fb8909 100644 --- a/docs/agentic-batch-changes/collaboration.mdx +++ b/docs/agentic-batch-changes/collaboration.mdx @@ -24,7 +24,7 @@ Each action runs as the user who does it, not as the owner. See [Whose credentia - Cancel and retry turns. - Run workspaces, publish, and clean up changesets that the current plan no longer produces. - Ask the agent to merge changesets, and approve the merge. - - Act on changesets on the batch change page: publish, push the branch, comment, close, merge, rebase, sync, and retry. + - Act on changesets on the batch change page: publish, push the branch, comment, close, merge, rebase, sync, and retry. - **Administrator** with the `BATCH_CHANGE_AGENT_ADMINISTRATION#MANAGE` [permission](/admin/access-control/batch-changes): sees every agent on the [Threads page](/agentic-batch-changes/configuration#threads-page), can hand over any agent, and can invite, extend, and remove collaborators. An administrator who is not a collaborator cannot send messages or act on the agent. - **Previous owner**: after a handover, the previous owner keeps read access to the agent. This access does not expire, and the previous owner cannot act on the agent. - **Viewer**: a user who opens the agent through its [share link](/agentic-batch-changes/configuration#sharing-and-visibility). A viewer can read the transcript but cannot act on the agent or see the collaborator list. From 0794e3b971e2eb6a0fcf162f38ba48985f07cc46 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 18 Nov 2026 08:51:45 +0000 Subject: [PATCH 04/10] docs/abc: Link coding agent step runs to entitlements Amp-Thread-ID: https://ampcode.com/threads/T-01a1e4d8-de7d-7217-baa1-3fb2338878a6 --- docs/agentic-batch-changes/collaboration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agentic-batch-changes/collaboration.mdx b/docs/agentic-batch-changes/collaboration.mdx index 8006a5737..f665c4e30 100644 --- a/docs/agentic-batch-changes/collaboration.mdx +++ b/docs/agentic-batch-changes/collaboration.mdx @@ -51,7 +51,7 @@ The user who sends the message, answers the question, approves the tool call, or - The agent researches and runs Deep Search as that user. Repository names the agent sees are limited to repositories that both the owner and that user can read. - Guidance and skills come from that user's settings and from the site and organization settings that apply to them. -- Workspaces and coding agent steps run as that user, with that user's secrets, connectors, and Sourcegraph MCP identity. Coding agent step runs count against that user's [usage limits](/agentic-batch-changes/configuration#usage-limits). +- Workspaces and coding agent steps run as that user, with that user's secrets, connectors, and Sourcegraph MCP identity. Coding agent step runs count against that user's [entitlement](/admin/entitlements). - Tool approvals belong to the user who gave them. An approval from one user does not count for a turn that runs as another user, also when the approval was for this agent or for all agents. When an action cannot run as that user, it is refused with a reason. It does not fall back to the owner. For example, a publish is refused when the user has no valid Batch Changes credential for a code host and there is no global credential, and a workspace fails when a secret it needs is not available to that user. From 657a4bc4b5a4a6dbeb34a542a86119cff53e0f7c Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 18 Nov 2026 08:58:27 +0000 Subject: [PATCH 05/10] docs/abc: Document collaboration as available to all ABC users --- docs/agentic-batch-changes/collaboration.mdx | 13 +------------ docs/agentic-batch-changes/configuration.mdx | 4 +--- 2 files changed, 2 insertions(+), 15 deletions(-) diff --git a/docs/agentic-batch-changes/collaboration.mdx b/docs/agentic-batch-changes/collaboration.mdx index f665c4e30..11cd4a9d3 100644 --- a/docs/agentic-batch-changes/collaboration.mdx +++ b/docs/agentic-batch-changes/collaboration.mdx @@ -1,9 +1,7 @@ # Collaboration - Collaboration is experimental and available only on [Sourcegraph - Cloud](/cloud). It is behind the `abc-collaboration` feature flag. To turn - it on for your instance, contact Sourcegraph. + Collaboration is experimental. Collaboration lets the owner of an agentic batch change invite other users to work on it. A collaborator can talk to the agent, answer its questions, run workspaces, and publish, for a fixed time. For example, a platform engineer who owns a framework migration invites a service team member for 24 hours to answer the agent's questions about that team's repositories and fix their CI failures. @@ -89,12 +87,3 @@ A [handover](/agentic-batch-changes/configuration#handing-over-an-agent) needs t - The previous owner keeps read access. - All publication approvals are removed. The new owner approves publications again. - Questions and approvals that wait stay open. The new owner or a collaborator can answer them, and the turn continues as that user. - -## Turning collaboration off - -When Sourcegraph turns off the `abc-collaboration` flag: - -- The collaborators panel is hidden, also for the owner. -- Collaborators can still open the agent and read the transcript, but they cannot send messages, answer questions, approve tool calls, cancel or retry turns, or act on changesets on the batch change page. -- Collaborator access is kept. If the flag is turned on again, access that has not expired works again. -- A turn that a collaborator started before the flag was turned off continues. diff --git a/docs/agentic-batch-changes/configuration.mdx b/docs/agentic-batch-changes/configuration.mdx index 5c4c44b8f..9567f5ccd 100644 --- a/docs/agentic-batch-changes/configuration.mdx +++ b/docs/agentic-batch-changes/configuration.mdx @@ -128,9 +128,7 @@ Both halves of a pair are required. All four are part of the built-in User role, ### Ownership -Each agentic batch change has one owner: the user who created it, until it is [handed over](#handing-over-an-agent). Only the owner can send messages, approve actions, run workspaces, and publish. Other users can read the conversation, the plan, and the results, but they cannot change anything; see [Sharing and visibility](#sharing-and-visibility). There is no co-ownership. Because the agent acts as its owner, the owner's repository permissions and Batch Changes credentials bound what it can touch. - -On Sourcegraph Cloud, the owner can invite collaborators who act on the agent with their own credentials. This is experimental. See [Collaboration](/agentic-batch-changes/collaboration). +Each agentic batch change has one owner: the user who created it, until it is [handed over](#handing-over-an-agent). The owner can invite [collaborators](/agentic-batch-changes/collaboration), who can also send messages, approve most actions, run workspaces, and publish. Other users can read the conversation, the plan, and the results, but they cannot change anything; see [Sharing and visibility](#sharing-and-visibility). There is no co-ownership: inviting collaborators, approving publications, and handing over stay with the owner. Each action runs with the repository permissions and Batch Changes credentials of the user who does it. ### Handing over an agent From a487d132bc88bb6b3964a8ff809113a6d5095b2f Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 18 Nov 2026 08:59:53 +0000 Subject: [PATCH 06/10] docs/abc: Say other users instead of colleagues Amp-Thread-ID: https://ampcode.com/threads/T-01a1e4d8-de7d-7217-baa1-3fb2338878a6 --- docs/agentic-batch-changes/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agentic-batch-changes/index.mdx b/docs/agentic-batch-changes/index.mdx index dcb2681d6..c0f195d61 100644 --- a/docs/agentic-batch-changes/index.mdx +++ b/docs/agentic-batch-changes/index.mdx @@ -64,4 +64,4 @@ If everything goes well, the agent might ask if it can continue. By default, the When configured to handle CI failures, the agent fetches the logs, iterates to fix the problem, and updates the changeset. You can step away and ask "what happened while I was away?" when you return for a summary of everything that changed. When reviewers approve and CI is green, merge on the code host or use **Merge** in Sourcegraph's changeset view, where available. The agent cannot merge changesets from the conversation. -To let colleagues follow the work, use **Share** on the agent page. See [Sharing and visibility](/agentic-batch-changes/configuration#sharing-and-visibility). To let a colleague take over the work, use **Share** > **Hand over**. See [Handing over an agent](/agentic-batch-changes/configuration#handing-over-an-agent). To work on it together with colleagues, invite them as collaborators. See [Collaboration](/agentic-batch-changes/collaboration). +To let other users follow the work, use **Share** on the agent page. See [Sharing and visibility](/agentic-batch-changes/configuration#sharing-and-visibility). To let another user take over the work, use **Share** > **Hand over**. See [Handing over an agent](/agentic-batch-changes/configuration#handing-over-an-agent). To work on it together with other users, invite them as collaborators. See [Collaboration](/agentic-batch-changes/collaboration). From 28fcee6d5ea02f7f4edd55e9f3157fa13fcb54cc Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 18 Nov 2026 09:18:25 +0000 Subject: [PATCH 07/10] docs/abc: Remove experimental callout from collaboration page Amp-Thread-ID: https://ampcode.com/threads/T-01a1e4d8-de7d-7217-baa1-3fb2338878a6 --- docs/agentic-batch-changes/collaboration.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/agentic-batch-changes/collaboration.mdx b/docs/agentic-batch-changes/collaboration.mdx index 11cd4a9d3..8b9643519 100644 --- a/docs/agentic-batch-changes/collaboration.mdx +++ b/docs/agentic-batch-changes/collaboration.mdx @@ -1,9 +1,5 @@ # Collaboration - - Collaboration is experimental. - - Collaboration lets the owner of an agentic batch change invite other users to work on it. A collaborator can talk to the agent, answer its questions, run workspaces, and publish, for a fixed time. For example, a platform engineer who owns a framework migration invites a service team member for 24 hours to answer the agent's questions about that team's repositories and fix their CI failures. Each action runs as the user who does it, not as the owner. See [Whose credentials an action uses](#whose-credentials-an-action-uses). From 17b5596a0f819401781c8d3ebef50fca3bb08c5f Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 18 Nov 2026 09:35:18 +0000 Subject: [PATCH 08/10] docs/abc: Drop batch change page references and say publish approval Amp-Thread-ID: https://ampcode.com/threads/T-01a1e4d8-de7d-7217-baa1-3fb2338878a6 --- docs/agentic-batch-changes/collaboration.mdx | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/agentic-batch-changes/collaboration.mdx b/docs/agentic-batch-changes/collaboration.mdx index 8b9643519..f8200e89e 100644 --- a/docs/agentic-batch-changes/collaboration.mdx +++ b/docs/agentic-batch-changes/collaboration.mdx @@ -8,16 +8,14 @@ Each action runs as the user who does it, not as the owner. See [Whose credentia - **Owner**: the user who created the agent, or who got it through a [handover](/agentic-batch-changes/configuration#handing-over-an-agent). There is one owner. The owner can do everything a collaborator can do, and also: - Invite, extend, and remove collaborators. - - Approve publications. + - Give publish approvals. - Hand over the agent. - Rename, share, stop, and delete the agent, and start new threads. - - Close, move, and delete the batch change. - **Collaborator**: a user the owner invited. A collaborator sees the full transcript and the list of collaborators, and can: - Send messages and upload files. - - Answer the agent's questions and approve tool calls, except publication approvals. + - Answer the agent's questions and approve tool calls, except publish approvals. - Cancel and retry turns. - Run workspaces, publish, and clean up changesets that the current plan no longer produces. - - Act on changesets on the batch change page: publish, push the branch, comment, close, merge, rebase, sync, and retry. - **Administrator** with the `BATCH_CHANGE_AGENT_ADMINISTRATION#MANAGE` [permission](/admin/access-control/batch-changes): sees every agent on the [Threads page](/agentic-batch-changes/configuration#threads-page), can hand over any agent, and can invite, extend, and remove collaborators. An administrator who is not a collaborator cannot send messages or act on the agent. - **Previous owner**: after a handover, the previous owner keeps read access to the agent. This access does not expire, and the previous owner cannot act on the agent. - **Viewer**: a user who opens the agent through its [share link](/agentic-batch-changes/configuration#sharing-and-visibility). A viewer can read the transcript but cannot act on the agent or see the collaborator list. @@ -58,11 +56,10 @@ In these cases, the user an action runs as or is charged to is not the user who - **Changeset hooks**: CI and merge conflict automations run as the user whose turn prepared the current plan. When a collaborator's turn prepared it, hooks use that collaborator's permissions, secrets, and connectors. - **Retry**: a retried turn runs as the user who clicks **Retry**, not as the author of the original message. - **Answers and approvals**: when a turn is waiting for an answer or an approval, any owner or collaborator can answer. The turn then continues as the user who answered. -- **Publication approvals**: only the owner can approve a publication. A collaborator can publish only to repositories and in a mode, such as draft, that the owner already approved for this agent. -- **Code host pushes and syncs**: Sourcegraph pushes and syncs all changesets of the batch change with the Batch Changes credential of the user who last applied it, or the global credential when that user has none. This also applies to changesets that another user published. Publishing from the conversation makes the publishing user the last applier. Publishing from the batch change page does not change the last applier, so the push uses the credential of the previous last applier. Comment, close, merge, and rebase use the credential of the user who starts them. +- **Publish approvals**: before the agent publishes, it shows an approval card. A publish approval covers specific repositories and a mode, such as draft. Only the owner can give a publish approval. A collaborator can publish only to repositories and in a mode that the owner already approved for this agent. +- **Code host pushes and syncs**: Sourcegraph pushes and syncs all changesets of the agent with the Batch Changes credential of the user who published most recently, or the global credential when that user has none. This also applies to changesets that another user published. - **Published changesets entitlement**: when a collaborator publishes, the published changeset counts against the collaborator's entitlement. When the owner publishes, it counts against the owner's. - **Billing**: merged changesets are [billed](/agentic-batch-changes/configuration#billing) to the subscription and recorded for the owner, no matter who published or merged them. -- **Batch change namespace**: the batch change stays in the owner's namespace, also when a collaborator's turn creates or updates it. - **Uploaded files**: files are stored with the agent under the owner, no matter who uploaded them. Every user who can open the agent can download them. - **Repository visibility at publish**: Sourcegraph checks that the owner can read the target repositories before it publishes, in addition to the publishing user's own permissions. @@ -81,5 +78,5 @@ A [handover](/agentic-batch-changes/configuration#handing-over-an-agent) needs t - Collaborators keep their access, except the new owner, who becomes the owner. - The previous owner keeps read access. -- All publication approvals are removed. The new owner approves publications again. +- All publish approvals are removed. The new owner gives publish approvals again. - Questions and approvals that wait stay open. The new owner or a collaborator can answer them, and the turn continues as that user. From 9b84e5673770b9cc3fe0eda908c6b98d0676e474 Mon Sep 17 00:00:00 2001 From: Michael Bahr <1830132+bahrmichael@users.noreply.github.com> Date: Wed, 18 Nov 2026 10:49:46 +0100 Subject: [PATCH 09/10] Apply batched suggestions from code review Co-authored-by: Michael Bahr <1830132+bahrmichael@users.noreply.github.com> --- docs/agentic-batch-changes/collaboration.mdx | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/docs/agentic-batch-changes/collaboration.mdx b/docs/agentic-batch-changes/collaboration.mdx index f8200e89e..a331187be 100644 --- a/docs/agentic-batch-changes/collaboration.mdx +++ b/docs/agentic-batch-changes/collaboration.mdx @@ -16,25 +16,19 @@ Each action runs as the user who does it, not as the owner. See [Whose credentia - Answer the agent's questions and approve tool calls, except publish approvals. - Cancel and retry turns. - Run workspaces, publish, and clean up changesets that the current plan no longer produces. -- **Administrator** with the `BATCH_CHANGE_AGENT_ADMINISTRATION#MANAGE` [permission](/admin/access-control/batch-changes): sees every agent on the [Threads page](/agentic-batch-changes/configuration#threads-page), can hand over any agent, and can invite, extend, and remove collaborators. An administrator who is not a collaborator cannot send messages or act on the agent. -- **Previous owner**: after a handover, the previous owner keeps read access to the agent. This access does not expire, and the previous owner cannot act on the agent. +- **Administrator**: sees every agent on the [Threads page](/agentic-batch-changes/configuration#threads-page), can hand over any agent, and can invite, extend, and remove collaborators. An administrator who is not a collaborator cannot send messages or act on the agent. +- **Previous owner**: after a handover, the previous owner keeps read access to the agent. - **Viewer**: a user who opens the agent through its [share link](/agentic-batch-changes/configuration#sharing-and-visibility). A viewer can read the transcript but cannot act on the agent or see the collaborator list. ## Inviting collaborators -The owner or an administrator invites collaborators from the collaborators panel on the agent page. To be invited, a user must: +The owner or an administrator invites collaborators from the collaborators panel on the agent page. To be invited, a user must have the `Batch Changes: Write` and `Batch Changes: Agent Write` [permissions](/agentic-batch-changes/configuration#access). -- Be a user on the instance other than the owner. -- Have the `Batch Changes: Write` and `Batch Changes: Agent Write` [permissions](/agentic-batch-changes/configuration#access). Sourcegraph refuses the invite otherwise. - -Sourcegraph does not check the collaborator's repository permissions when they are invited. The collaborator's own repository permissions apply when they act. See [Whose credentials an action uses](#whose-credentials-an-action-uses). +Sourcegraph does not block the invite if the collaborator's repository permissions are not sufficient. The collaborator's own repository permissions apply when they act and they only see repos and changesets that they have permission for. See [Whose credentials an action uses](#whose-credentials-an-action-uses). Every collaborator access expires. Select 1 hour, 24 hours, or 7 days when you invite. There is no access without an expiry and no limit on the number of collaborators. The invited user gets a notification in Sourcegraph, and the access starts immediately. To extend access, select a new duration. The access then ends that long from now, not from the old end time. After access expires or is removed, invite the user again. - -A collaborator cannot leave an agent. Access ends when it expires or when the owner or an administrator removes it. Removing a user's `Batch Changes: Agent Write` permission also stops them from acting on the agent. - The [audit log](/agentic-batch-changes/configuration#audit-log) records `collaboratorInvited`, `collaboratorExtended`, and `collaboratorRevoked` with the owner, the collaborator, the user who made the change, and the expiry. Conversation and workspace actions record both the owner and the user who acted. ## Whose credentials an action uses @@ -46,7 +40,7 @@ The user who sends the message, answers the question, approves the tool call, or - Workspaces and coding agent steps run as that user, with that user's secrets, connectors, and Sourcegraph MCP identity. Coding agent step runs count against that user's [entitlement](/admin/entitlements). - Tool approvals belong to the user who gave them. An approval from one user does not count for a turn that runs as another user, also when the approval was for this agent or for all agents. -When an action cannot run as that user, it is refused with a reason. It does not fall back to the owner. For example, a publish is refused when the user has no valid Batch Changes credential for a code host and there is no global credential, and a workspace fails when a secret it needs is not available to that user. +When an action cannot run as that user, it is refused with a reason. It does not fall back to the owner. For example, a publish is refused when the user has no valid Batch Changes credential for a code host and there is no global credential. A workspace fails when a secret it needs is not available to that user. ### Exceptions @@ -58,7 +52,6 @@ In these cases, the user an action runs as or is charged to is not the user who - **Answers and approvals**: when a turn is waiting for an answer or an approval, any owner or collaborator can answer. The turn then continues as the user who answered. - **Publish approvals**: before the agent publishes, it shows an approval card. A publish approval covers specific repositories and a mode, such as draft. Only the owner can give a publish approval. A collaborator can publish only to repositories and in a mode that the owner already approved for this agent. - **Code host pushes and syncs**: Sourcegraph pushes and syncs all changesets of the agent with the Batch Changes credential of the user who published most recently, or the global credential when that user has none. This also applies to changesets that another user published. -- **Published changesets entitlement**: when a collaborator publishes, the published changeset counts against the collaborator's entitlement. When the owner publishes, it counts against the owner's. - **Billing**: merged changesets are [billed](/agentic-batch-changes/configuration#billing) to the subscription and recorded for the owner, no matter who published or merged them. - **Uploaded files**: files are stored with the agent under the owner, no matter who uploaded them. Every user who can open the agent can download them. - **Repository visibility at publish**: Sourcegraph checks that the owner can read the target repositories before it publishes, in addition to the publishing user's own permissions. From 66aa5e5f48303414b446b9b26e38b77df7ab4710 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 18 Nov 2026 09:54:35 +0000 Subject: [PATCH 10/10] docs/abc: Split audit log paragraph Amp-Thread-ID: https://ampcode.com/threads/T-01a1e4d8-de7d-7217-baa1-3fb2338878a6 --- docs/agentic-batch-changes/collaboration.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/agentic-batch-changes/collaboration.mdx b/docs/agentic-batch-changes/collaboration.mdx index 18a743bea..67fb04603 100644 --- a/docs/agentic-batch-changes/collaboration.mdx +++ b/docs/agentic-batch-changes/collaboration.mdx @@ -30,6 +30,7 @@ Sourcegraph does not block the invite if the collaborator's repository permissio Every collaborator access expires. Select 1 hour, 24 hours, or 7 days when you invite. There is no access without an expiry and no limit on the number of collaborators. The invited user gets a notification in Sourcegraph, and the access starts immediately. To extend access, select a new duration. The access then ends that long from now, not from the old end time. After access expires or is removed, invite the user again. + The [audit log](/agentic-batch-changes/configuration#audit-log) records `collaboratorInvited`, `collaboratorExtended`, and `collaboratorRevoked` with the owner, the collaborator, the user who made the change, and the expiry. Conversation and workspace actions record both the owner and the user who acted. ## Whose credentials an action uses