Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
45dd718
docs/abc: Document collaboration roles and whose credentials each act…
bahrmichael Nov 18, 2026
1d44f8f
docs/abc: Document that the agent can merge changesets
bahrmichael Nov 18, 2026
9e56f85
docs/abc: Fix collaborator list indentation
bahrmichael Nov 18, 2026
0794e3b
docs/abc: Link coding agent step runs to entitlements
bahrmichael Nov 18, 2026
39c1db9
Merge branch 'michaelbahr-cpl-1333-docs-document-abc-collaboration-ro…
bahrmichael Nov 18, 2026
657a4bc
docs/abc: Document collaboration as available to all ABC users
bahrmichael Nov 18, 2026
2a77914
Merge branch 'michaelbahr-cpl-1333-docs-document-abc-collaboration-ro…
bahrmichael Nov 18, 2026
a487d13
docs/abc: Say other users instead of colleagues
bahrmichael Nov 18, 2026
0dfa320
Merge branch 'michaelbahr-cpl-1333-docs-document-abc-collaboration-ro…
bahrmichael Nov 18, 2026
28fcee6
docs/abc: Remove experimental callout from collaboration page
bahrmichael Nov 18, 2026
0851537
Merge branch 'michaelbahr-cpl-1333-docs-document-abc-collaboration-ro…
bahrmichael Nov 18, 2026
17b5596
docs/abc: Drop batch change page references and say publish approval
bahrmichael Nov 18, 2026
6dc1e54
Merge branch 'michaelbahr-cpl-1333-docs-document-abc-collaboration-ro…
bahrmichael Nov 18, 2026
9b84e56
Apply batched suggestions from code review
bahrmichael Nov 18, 2026
596f1b4
Merge remote-tracking branch 'origin/michaelbahr-abc-docs-agent-merge…
bahrmichael Nov 18, 2026
66aa5e5
docs/abc: Split audit log paragraph
bahrmichael Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions docs/admin/access-control/batch-changes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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` | <ul><li>User can view batch changes, changesets, and batch specs.</li><li>User can view bulk operations and batch spec workspaces.</li></ul> | ✓ |
| `batch_changes:write` | <ul><li>User can create, update, close, or delete batch changes.</li><li>User can create, execute, and apply batch specs.</li><li>User can perform bulk operations on changesets such as publishing, commenting on, closing, or merging them.</li></ul> | ✓ |
| `batch_changes:agent_read` | <ul><li>User can view [agentic batch changes](/agentic-batch-changes/), including agents, their conversations, and results.</li><li>Requires `batch_changes:read` as well.</li></ul> | ✓ |
| `batch_changes:agent_write` | <ul><li>User can create, run, and modify [agentic batch changes](/agentic-batch-changes/).</li><li>Requires `batch_changes:write` as well.</li></ul> | ✓ |
| `batch_change_agent_administration:manage` | <ul><li>User can list and open every user's [agentic batch changes](/agentic-batch-changes/) on the [Threads page](/agentic-batch-changes/configuration#threads-page), regardless of the sharing setting.</li><li>User can [hand over](/agentic-batch-changes/configuration#handing-over-an-agent) any agentic batch change to another user.</li><li>Requires `batch_changes:read` and `batch_changes:agent_read` to open the Threads page, and `batch_changes:write` and `batch_changes:agent_write` to hand over.</li></ul> | |
| Name | Description | Granted to **User** by default? |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-----------------------------: |
| `batch_changes:read` | <ul><li>User can view batch changes, changesets, and batch specs.</li><li>User can view bulk operations and batch spec workspaces.</li></ul> | ✓ |
| `batch_changes:write` | <ul><li>User can create, update, close, or delete batch changes.</li><li>User can create, execute, and apply batch specs.</li><li>User can perform bulk operations on changesets such as publishing, commenting on, closing, or merging them.</li></ul> | ✓ |
| `batch_changes:agent_read` | <ul><li>User can view [agentic batch changes](/agentic-batch-changes/), including agents, their conversations, and results.</li><li>Requires `batch_changes:read` as well.</li></ul> | ✓ |
| `batch_changes:agent_write` | <ul><li>User can create, run, and modify [agentic batch changes](/agentic-batch-changes/).</li><li>User can be invited as a [collaborator](/agentic-batch-changes/collaboration) on another user's agentic batch change.</li><li>Requires `batch_changes:write` as well.</li></ul> | ✓ |
| `batch_change_agent_administration:manage` | <ul><li>User can list and open every user's [agentic batch changes](/agentic-batch-changes/) on the [Threads page](/agentic-batch-changes/configuration#threads-page), regardless of the sharing setting.</li><li>User can [hand over](/agentic-batch-changes/configuration#handing-over-an-agent) any agentic batch change to another user.</li><li>User can invite, extend, and remove [collaborators](/agentic-batch-changes/collaboration) on any agentic batch change.</li><li>Requires `batch_changes:read` and `batch_changes:agent_read` to open the Threads page, and `batch_changes:write` and `batch_changes:agent_write` to hand over.</li></ul> | |

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.

Expand Down
77 changes: 77 additions & 0 deletions docs/agentic-batch-changes/collaboration.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Collaboration

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.
- Give publish approvals.
- Hand over the agent.
- Rename, share, stop, and delete the agent, and start new threads.
- **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 publish approvals.
- 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.
- **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 have the `Batch Changes: Write` and `Batch Changes: Agent Write` [permissions](/agentic-batch-changes/configuration#access).

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.

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 [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. 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.
- **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. A merge uses the credential of the user whose turn asked for it.
- **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.

## 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 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.
2 changes: 1 addition & 1 deletion docs/agentic-batch-changes/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +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.
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

Expand Down
Loading
Loading