docs(network-broker): document the scms list in v0.47.0 by matthewdean-semgrep · Pull Request #2844 · semgrep/semgrep-docs

matthewdean-semgrep · 2026-09-21T22:12:44Z

Sister PR to semgrep/semgrep-network-broker#236, released in v0.47.0.

Why

The Network Broker page only documents the single-SCM keys (github, gitlab, bitbucket, azuredevops). Each key holds one instance, so a second instance of the same type needs a hand-written allowlist with a token on every rule. v0.47.0 adds inbound.scms, a list whose entries each carry their own type:

inbound:
  scms:
    - type: github
      baseUrl: https://GITHUB_BASE_URL/api/v3
    - type: github
      baseUrl: https://SECOND_GITHUB_BASE_URL/api/v3
      allowCodeAccess: true

Approach

Create the config file gains a v0.47.0 and later tab that uses scms. The old v0.25.0 and later tab becomes v0.25.0 to v0.46.0. Allowlist multiple source code managers now leads with scms, and the hand-written allowlist moves to a v0.46.0 and earlier tab. Headings are unchanged, so inbound anchors still resolve.

The SCM information and Managed Scans steps keep their per-SCM tabs. Each gets one sentence on how to express the same thing as an scms entry, because the single-SCM keys still work in v0.47.0.

The page also covers the two ways scms behaves differently from the rest of the config:

With multiple -c files, entries that share type and baseUrl merge field by field. The page says elsewhere that arrays are replaced, so this needs its own note.
The broker refuses to start when the same instance appears both in scms and under a single-SCM key. It also refuses when two GitHub, GitLab, or Bitbucket entries of one type share a host and either sets allowCodeAccess.

Testing

I built the broker from the v0.47.0 tag and ran dump against configs modeled on the page:

The multiple-SCM example loads with allowCodeAccess set only on the second GitHub entry.
A later file with allowCodeAccess: true for the first GitHub entry amends that entry, even with a trailing slash on baseUrl.
inbound.github plus an scms entry for the same URL fails with declare it in one place.
Two GitLab entries on one host with allowCodeAccess fail with share host.

I haven't checked the Mintlify preview yet.

Thanks for improving Semgrep Docs

Please ensure:

A subject matter expert reviews the content
A technical writer reviews the PR
This change has no security implications or else you have pinged the security team
Any redirects are in docs/docs.json if URLs changed
If you edited docs/extensions/pre-commit.md.template.mdx, CI regenerates pre-commit.mdx on this PR (no manual run-build-scripts needed)
Check the Mintlify bot preview link on this PR (requires PR to main)

🤖 Generated with Claude Code

Network Broker v0.47.0 adds inbound.scms, a list whose entries each carry their own type. It lets one broker reach several instances of the same SCM type. The page only showed the single-SCM keys, so a second instance of the same type still needed a hand-written allowlist with a token on every rule. The config file steps gain a v0.47.0 tab, and the multiple-SCM section leads with scms. The earlier instructions stay in tabs for v0.46.0 and earlier. The page also covers the two ways scms differs from the rest of the config: files merge entries by type and baseUrl instead of replacing the list, and the broker refuses to start when two entries would share allowlist rules. Co-Authored-By: Claude Code <noreply@anthropic.com>

mintlify · 2026-09-21T22:12:48Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
semgrep-docs	🟢 Ready	View Preview	Sep 22, 2026, 9:49 PM

armchairlinguist · 2026-09-21T22:37:08Z


 Note that arrays are replaced, while maps are merged.

+The `scms` list in v0.47.0 and later is an exception. The broker identifies each entry by its `type` and `baseUrl`. It merges entries that share both field by field, and the later file wins. It keeps entries that differ in either field side by side.


field by field and side by side here are a little confusing to me - can you describe this in a way that's less ambiguous?

armchairlinguist · 2026-09-21T22:38:40Z


 Update the `config.yaml` by replacing the SCM information containing `YOUR_BASE_URL` with your SCM and its base URL for Azure DevOps, GitHub, GitLab, or Bitbucket Data Center.

+If you use `scms` in v0.47.0 and later, set the entry's `type` to the key shown in the tab for your SCM, which is `azuredevops`, `bitbucket`, `github`, or `gitlab`. Set its `baseUrl` to the base URL shown in the same tab.


Suggested change

If you use `scms` in v0.47.0 and later, set the entry's `type` to the key shown in the tab for your SCM, which is `azuredevops`, `bitbucket`, `github`, or `gitlab`. Set its `baseUrl` to the base URL shown in the same tab.

If you use the `scms` key with an SCM list, available in v0.47.0 and later, set each entry's `type` to the key shown in the tab for your SCM: either `azuredevops`, `bitbucket`, `github`, or `gitlab`. Set its `baseUrl` to the base URL value shown in that same tab.

armchairlinguist · 2026-09-21T22:39:01Z

 </Tab>
 </Tabs>

+If you use `scms` in v0.47.0 and later, add `allowCodeAccess: true` to each entry that needs code access. The setting applies only to the entry that sets it.


Suggested change

If you use `scms` in v0.47.0 and later, add `allowCodeAccess: true` to each entry that needs code access. The setting applies only to the entry that sets it.

If you use the `scms` key with an SCM list, available in v0.47.0 and later, add `allowCodeAccess: true` to each entry that needs code access. The setting applies only to the entry that sets it.

armchairlinguist · 2026-09-21T22:40:35Z

+
+Each entry requires `type` and `baseUrl`. It also accepts `token` and `allowCodeAccess`, which apply only to that entry. The broker allows the same endpoints for each entry that it allows for the matching [SCM-specific key](/semgrep-ci/network-broker#update-the-config-with-your-scm-information).
+
+You can combine `scms` with SCM-specific keys, such as `github`, as long as they name different instances. The broker exits with an error at startup in the following cases:


Suggested change

You can combine `scms` with SCM-specific keys, such as `github`, as long as they name different instances. The broker exits with an error at startup in the following cases:

You can use both `scms` and SCM-specific keys, such as `github`, as long as the same instance is not named twice. The broker exits with an error at startup in the following cases:

armchairlinguist · 2026-09-21T22:42:27Z

+You can combine `scms` with SCM-specific keys, such as `github`, as long as they name different instances. The broker exits with an error at startup in the following cases:
+
+- An SCM-specific key and an `scms` entry have the same type and base URL.
+- Two GitHub, GitLab, or Bitbucket entries of the same type share a host, and at least one of them sets `allowCodeAccess: true`. The broker allows repository cloning for these SCMs by host, so it can't keep the clone access and tokens of the two instances apart. Give each instance its own host, or leave `allowCodeAccess` unset on every instance on that host.


Suggested change

- Two GitHub, GitLab, or Bitbucket entries of the same type share a host, and at least one of them sets `allowCodeAccess: true`. The broker allows repository cloning for these SCMs by host, so it can't keep the clone access and tokens of the two instances apart. Give each instance its own host, or leave `allowCodeAccess` unset on every instance on that host.

- For GitHub, GitLab, and Bitbucket: if two entries of the same type share a host and at least one of them sets `allowCodeAccess: true`. The broker allows repository cloning for these SCMs by host, so it can't have different code access settings for the same host. Give each instance its own host, or leave `allowCodeAccess` unset on every instance on that host.

abhijna

Ltgm! Agree with Alexis' comments. Made a couple of tiny edits

abhijna · 2026-09-22T17:27:59Z


 Note that arrays are replaced, while maps are merged.

+The `scms` list in v0.47.0 and later is an exception. The broker identifies each entry by its `type` and `baseUrl`. It merges entries that share both field by field, and the later file wins. It keeps entries that differ in either field side by side.


Suggested change

The `scms` list in v0.47.0 and later is an exception. The broker identifies each entry by its `type` and `baseUrl`. It merges entries that share both field by field, and the later file wins. It keeps entries that differ in either field side by side.

The `scms` list in v0.47.0 and later is an exception. The broker matches entries that have the same

`type` and `baseUrl` and combines them into one entry. It keeps a key that only one file sets, such

as `token`. If both files set the same key, it uses the value from the later file. Entries with a

different `type` or `baseUrl` are both kept. A later file does not replace the list.

How's this? ^

Reviewers found the multiple-config merge rule ambiguous and asked for the `scms` mentions to name the key the same way each time. The merge paragraph now spells out the behavior key by key rather than leaning on "field by field" and "side by side". The three cross-references to the list say "the `scms` key with an SCM list", and the shared-host error case leads with the SCMs it applies to. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

mintlify Bot deployed to staging - docs September 21, 2026 22:13 View deployment

matthewdean-semgrep requested review from abhijna, armchairlinguist and semgrep-jamie September 21, 2026 22:22

matthewdean-semgrep marked this pull request as ready for review September 21, 2026 22:22

armchairlinguist reviewed Sep 21, 2026

View reviewed changes

abhijna approved these changes Sep 22, 2026

View reviewed changes

mintlify Bot deployed to staging - docs September 22, 2026 21:49 View deployment

Navigation Menu

docs(network-broker): document the scms list in v0.47.0 - #2844

docs(network-broker): document the scms list in v0.47.0#2844
matthewdean-semgrep wants to merge 2 commits into
mainfrom
matthewdean/broker-scms-list

matthewdean-semgrep commented Sep 21, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Sep 21, 2026 •

edited

Loading

Uh oh!

armchairlinguist Sep 21, 2026

Uh oh!

armchairlinguist Sep 21, 2026 •

edited by abhijna

Loading

Uh oh!

armchairlinguist Sep 21, 2026

Uh oh!

armchairlinguist Sep 21, 2026

Uh oh!

armchairlinguist Sep 21, 2026 •

edited by abhijna

Loading

Uh oh!

abhijna left a comment

Uh oh!

abhijna Sep 22, 2026

Uh oh!

abhijna Sep 22, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		Note that arrays are replaced, while maps are merged.

		The `scms` list in v0.47.0 and later is an exception. The broker identifies each entry by its `type` and `baseUrl`. It merges entries that share both field by field, and the later file wins. It keeps entries that differ in either field side by side.


		Update the `config.yaml` by replacing the SCM information containing `YOUR_BASE_URL` with your SCM and its base URL for Azure DevOps, GitHub, GitLab, or Bitbucket Data Center.

		If you use `scms` in v0.47.0 and later, set the entry's `type` to the key shown in the tab for your SCM, which is `azuredevops`, `bitbucket`, `github`, or `gitlab`. Set its `baseUrl` to the base URL shown in the same tab.

	If you use `scms` in v0.47.0 and later, set the entry's `type` to the key shown in the tab for your SCM, which is `azuredevops`, `bitbucket`, `github`, or `gitlab`. Set its `baseUrl` to the base URL shown in the same tab.
	If you use the `scms` key with an SCM list, available in v0.47.0 and later, set each entry's `type` to the key shown in the tab for your SCM: either `azuredevops`, `bitbucket`, `github`, or `gitlab`. Set its `baseUrl` to the base URL value shown in that same tab.


		Each entry requires `type` and `baseUrl`. It also accepts `token` and `allowCodeAccess`, which apply only to that entry. The broker allows the same endpoints for each entry that it allows for the matching [SCM-specific key](/semgrep-ci/network-broker#update-the-config-with-your-scm-information).

		You can combine `scms` with SCM-specific keys, such as `github`, as long as they name different instances. The broker exits with an error at startup in the following cases:

	You can combine `scms` with SCM-specific keys, such as `github`, as long as they name different instances. The broker exits with an error at startup in the following cases:
	You can use both `scms` and SCM-specific keys, such as `github`, as long as the same instance is not named twice. The broker exits with an error at startup in the following cases:

	- Two GitHub, GitLab, or Bitbucket entries of the same type share a host, and at least one of them sets `allowCodeAccess: true`. The broker allows repository cloning for these SCMs by host, so it can't keep the clone access and tokens of the two instances apart. Give each instance its own host, or leave `allowCodeAccess` unset on every instance on that host.
	- For GitHub, GitLab, and Bitbucket: if two entries of the same type share a host and at least one of them sets `allowCodeAccess: true`. The broker allows repository cloning for these SCMs by host, so it can't have different code access settings for the same host. Give each instance its own host, or leave `allowCodeAccess` unset on every instance on that host.

-The `scms` list in v0.47.0 and later is an exception. The broker identifies each entry by its `type` and `baseUrl`. It merges entries that share both field by field, and the later file wins. It keeps entries that differ in either field side by side.
+The `scms` list in v0.47.0 and later is an exception. The broker matches entries that have the same
+`type` and `baseUrl` and combines them into one entry. It keeps a key that only one file sets, such
+as `token`. If both files set the same key, it uses the value from the later file. Entries with a
+different `type` or `baseUrl` are both kept. A later file does not replace the list.

Conversation

matthewdean-semgrep commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

Approach

Testing

Thanks for improving Semgrep Docs

Uh oh!

mintlify Bot commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

armchairlinguist Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

armchairlinguist Sep 21, 2026 • edited by abhijna Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

armchairlinguist Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

armchairlinguist Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

armchairlinguist Sep 21, 2026 • edited by abhijna Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

abhijna left a comment

Choose a reason for hiding this comment

Uh oh!

abhijna Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

abhijna Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

matthewdean-semgrep commented Sep 21, 2026 •

edited

Loading

mintlify Bot commented Sep 21, 2026 •

edited

Loading

armchairlinguist Sep 21, 2026 •

edited by abhijna

Loading

armchairlinguist Sep 21, 2026 •

edited by abhijna

Loading