# Agentic Batch Changes

Agentic Batch Changes turns a description of a change into changesets across your codebase. You tell the agent what should be different. It researches your repositories with [Deep Search](/deep-search), proposes a plan, previews the change on one repository, and rolls it out in stages you control. After it opens pull requests, it can keep watching them: when CI fails or a merge conflict appears, it can iterate to fix the problem and report back.

You can use it for:

- Dependency upgrades and CVE remediation, including upgrades with breaking changes, transitive dependencies, and lockfiles.
- Language and framework migrations, such as replacing deprecated APIs across every service.
- Generating or refreshing repository documentation and `AGENTS.md` guidance for coding agents.
- Splitting one large change in a monorepo into a separate pull request per team.

The agent also handles changes that need judgment in each repository, reading the surrounding code before it edits rather than applying one pattern everywhere.

Some terms used in this documentation:

- A **code host** is the service that hosts your repositories and reviews, such as GitHub, GitLab, Bitbucket, or Azure DevOps.
- A **changeset** is one proposed change on a code host: a pull request on GitHub, a merge request on GitLab. One agentic batch change can span several code hosts, so this documentation uses the neutral word.
- The **plan** is what the agent proposes before it runs: the repositories in scope, what will change in each one, and the branch, title, and commit message for the resulting changesets.

## Getting started

### Before you start

Agentic Batch Changes should be on by default. If it isn't available, contact your Sourcegraph administrator; see [Administration](/agentic-batch-changes/configuration#administration) for access and setup requirements.

As a user, you need:

- A [Batch Changes credential](/batch-changes/configuring-credentials) for each code host where the agent should publish, added under **Code hosts** in your Batch Changes settings.
- If you want the agent to react to CI failures, CI must report check results to your code host so Sourcegraph can detect them. Fetching CI logs also requires a token that can read them, stored under [**Secrets**](/admin/executors/executor-secrets#creating-a-new-secret) in the same settings area. See [Security and secrets](/agentic-batch-changes/configuration#security-and-secrets).

### Write the prompt

Open **Agentic Batch Changes** from the navigation and describe the change: the outcome you want and where to look.

For example, for a Go codebase:

> Across the repositories in our acme-platform organization, replace calls to `ioutil.ReadFile` with `os.ReadFile` and remove imports that become unused. Run `gofmt` afterwards. Don't touch anything under `vendor/`. Publish drafts so I can see CI.

See [Writing prompts](/agentic-batch-changes/writing-prompts) for more examples.

### Review the plan

The agent researches your codebase and comes back with a plan: the repositories in scope, what will change in each one, the branch and title for the changesets, and which repository it wants to test on first (also called a **canary**). The agent might ask clarifying questions when the scope is ambiguous.

At any time, you can ask the agent to show you the plan or adjust it in plain language, including after publication. You can ask for corrective code changes to existing changesets; see [During the conversation](/agentic-batch-changes/writing-prompts#during-the-conversation) for how revisions affect completed work.

### Watch the test run

After you approve, the agent runs the change in one repository and shows you the diff. Review the proposed changes and assess the agent's suggested solution. If the diff has a problem, tell the agent. You can also highlight and comment on lines in the diff itself. The agent will then revise the plan and adjust the next changes as well.

### Publish a draft

Where your code host supports drafts, tell the agent to publish the test result as a draft changeset to get CI, code owner checks, and reviewer comments on one changeset before the rollout goes any wider. If the agent needs a secret to read CI logs, it might ask you to [configure one](/agentic-batch-changes/configuration#security-and-secrets).

### Expand the rollout

If everything goes well, the agent might ask if it can continue. By default, the agent runs the next stage and pauses again when it's done. Each pause is a checkpoint where you can inspect a diff, skip a repository, or adjust a title. When you trust the change, "run everything else" fans out the remainder.

### 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.