From d443156456a64dcbd750ee92f6401d8c3d7bc510 Mon Sep 17 00:00:00 2001 From: Keegan Carruthers-Smith Date: Mon, 2 Feb 2026 15:53:05 +0200 Subject: [PATCH] feat/batch-changes: document maxConcurrency batch spec field Add documentation for the new maxConcurrency field that allows batch change authors to limit how many workspace execution jobs run concurrently during server-side execution. This helps avoid overwhelming CI systems or hitting rate limits on external services. The field takes the minimum of the specified value and the instance-wide execution limit configured by site administrators. Test Plan: Verified the documentation builds locally and follows the existing style for other batch spec fields. Changelog: Added documentation for the maxConcurrency batch spec field that limits concurrent workspace executions during server-side batch changes. Amp-Thread-ID: https://ampcode.com/threads/T-019c1e9e-3f2b-700f-9000-cbda85a35e69 Co-authored-by: Amp --- .../batch-spec-yaml-reference.mdx | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/batch-changes/batch-spec-yaml-reference.mdx b/docs/batch-changes/batch-spec-yaml-reference.mdx index 5a28ebdfd..82b5d90c5 100644 --- a/docs/batch-changes/batch-spec-yaml-reference.mdx +++ b/docs/batch-changes/batch-spec-yaml-reference.mdx @@ -523,6 +523,67 @@ The repository name as configured on your Sourcegraph instance. The changesets to import from the code host. For GitHub, this is the pull request number; for GitLab, this is the merge request number; and for Bitbucket Server, Bitbucket Data Center, or Bitbucket Cloud, this is the pull request number. +## `maxConcurrency` + +The maximum number of workspaces that can execute concurrently for this batch change during server-side execution. When specified, limits how many workspace execution jobs can run simultaneously. + +This is useful when: +- You want to avoid overwhelming CI systems that are triggered by batch change commits +- You need to stay within rate limits on external services your steps interact with +- You want to control resource consumption for large batch changes that span many repositories + +The effective concurrency limit is the **minimum** of: +1. This `maxConcurrency` value (if specified) +2. The instance-wide execution limit configured by site administrators + +If not specified, only the instance-wide limit applies. + + + This field only affects server-side execution. It has no effect when running batch specs locally with `src batch preview` or `src batch apply`. + + +### Examples + +Limit to 5 concurrent workspace executions: + +```yaml +name: update-dependencies +maxConcurrency: 5 + +on: + - repositoriesMatchingQuery: file:package.json + +steps: + - run: npm update + container: node:18 + +changesetTemplate: + title: Update npm dependencies + branch: update-deps + commit: + message: Update npm dependencies +``` + +For batch changes that trigger CI on each repository, limit concurrency to avoid overloading CI infrastructure: + +```yaml +name: security-fix +maxConcurrency: 3 + +on: + - repositoriesMatchingQuery: file:go.mod + +steps: + - run: go get -u ./... && go mod tidy + container: golang:1.21 + +changesetTemplate: + title: Update Go dependencies for security fixes + branch: security-deps-update + commit: + message: Update Go dependencies +``` + ## `changesetTemplate` A template describing how to create (and update) changesets with the file changes produced by the command steps.