Monorepository Management¶

Monorepository (monorepo) structures allow teams to organize multiple projects within a single repository. To leverage this setup in your AppSec program, define your monorepo structures in the Asset Management page. Boost lets you identify repositories as monorepos and map out their sub-repo layout and locations. You can configure these directly through the UI or use a bulk CSV upload based on this simple format.

Once defined, those sub-repos will behave within Boost like any other repository, allowing you to assign specific policies, provision specific coverage, and view findings against those sub-repos. See How Sub-repositories Behave.

How to Create Monorepositories¶

Follow these steps to create monorepositories and define their sub-repositories either manually or through a bulk CSV upload.

Navigate to the Scanner Coverage page and make sure that the repository has no scan enabled and no scan results by deleting all scans using the Advanced mode.
Navigate to the Asset Management page. Ensure that assets are grouped by Organization and that the Asset Type is set to Repositories.
Select the vertical ellipsis (three dots) on the right of any repository and choose Create Monorepo.
In the Monorepo creation interface, start defining the sub-repositories within the Monorepo structure.
Enter the path and name for each sub-repository, and click Add to include the sub-repository in the list of sub-repositories configured for this monorepo. The path and name must follow the path and name rules.

Warning

The name is the identity of the sub-repository: renaming it later, even only its case, creates a new asset and orphans the previous one with its findings. See Editing, Renaming and Removing Sub-repositories.
If you need to create many sub-repositories, use a .CSV file upload with the format to set the entire sub-repository structure in one action.

Be aware that any CSV file upload will overwrite all existing configurations for this monorepo.

Any sub-repository missing from the file is removed, along with its findings. See Editing, Renaming and Removing Sub-repositories.

This approach is more efficient than adding sub-repositories one at a time manually.

How Sub-repositories Behave¶

Each sub-repository is a separate asset, with its own scanners, findings, policies, tags, and pull request or merge request checks.

Settings applied to the parent repository don't cascade to its sub-repositories. Tags, policies, asset groups, and scanners on the parent apply only to the parent.
Selecting the parent repository doesn't select its sub-repositories. To act on a sub-repository, for example to provision a scanner or assign a tag, select the sub-repository itself.
A new sub-repository starts with no scanners, and the parent repository stops scanning its path. Provision scanners on it from the Scanner Coverage page. See Scanning the Parent Repository.
A sub-repository can have its own .boostignore file at the root of its path. That file replaces, for the sub-repository, both the Global Boostignore defined on the Boostignore page and the .boostignore file at the root of the parent repository. When the sub-repository has none, the Global Boostignore applies.

Path and Name Rules¶

Each sub-repository has a path and a name:

Path: a directory relative to the repository root, for example services/api. The path has no leading ./ or / and no trailing /.
Name: the name under which the sub-repository appears in Boost Security.

Names must be unique within the monorepo, and so must paths. The path must not be empty or .: the repository root is the parent repository, never a sub-repository.

Path	Valid	Reason
`services/api`	Yes	Directory relative to the repository root
`frontend`	Yes	Directory relative to the repository root
`./services/api`	No	Leading `./`
`/services/api`	No	Leading `/`
`services/api/`	No	Trailing `/`
`.`	No	The root is the parent repository
(empty)	No	The root is the parent repository

Warning

The UI accepts an empty path without an error. Always enter the directory of the sub-repository.

Boost Security doesn't check that the path exists on the scanned branch. Scans of a sub-repository whose path doesn't exist fail.

A repository can have either sub-repositories or additional monitored branches, not both.

Editing, Renaming and Removing Sub-repositories¶

The name of a sub-repository is its identity in Boost Security:

Changing only the path keeps the same asset.
Renaming a sub-repository, even when only the case of its name changes, creates a new asset under the new name. The asset under the previous name becomes an orphaned asset and keeps the existing findings with their triage state, such as suppressions and tickets. New scans report their findings, untriaged, on the new asset.
Removing a sub-repository removes its findings. Adding it back later creates a new asset.

Warning

A CSV upload replaces the whole list of sub-repositories of the monorepo. Any sub-repository missing from the file is removed, along with its findings.

How Scans Are Triggered in a Monorepo¶

When a commit or a pull request changes files in a monorepo, Boost Security runs scanners based on the paths of the changed files:

Changes under the path of a sub-repository run only the scanners provisioned on the sub-repositories whose path contains them.
Changes outside all sub-repository paths run the scanners provisioned on the parent repository. See Scanning the Parent Repository.
Changes under nested paths, such as services and services/api, run the scanners of every sub-repository whose path contains them: the content of a nested sub-repository is not excluded from the sub-repository that contains it. Avoid nesting sub-repositories.

A pull request that touches several areas starts one scan per area for each scanner provisioned on that area. The parent repository counts as one area when files outside all sub-repository paths change. For example, a pull request that changes files in the parent repository and in two sub-repositories, with two scanners each, starts up to six scans. Plan your runner capacity accordingly.

Note

The checks of the same scanner in different sub-repositories can carry identical names. As a result, you can't make the check of one specific sub-repository a required check in your branch protection rules.

Scanning the Parent Repository¶

The scans of the parent repository exclude the paths of all its sub-repositories, for every scanner. A file under the path of a sub-repository is scanned only by the scanners of the sub-repositories whose path contains it. A file outside all sub-repository paths is scanned only by the scanners of the parent repository.

You can therefore provision the same scanners on the parent repository and on its sub-repositories without getting duplicate findings between the parent and its sub-repositories. Scanners on the parent repository also cover files outside the declared sub-repositories, for example a new project directory not yet declared as a sub-repository.

Note

Declaring a sub-repository removes its path from the scans of the parent repository. Provision scanners on the new sub-repository, otherwise its files are no longer scanned.

Findings of the parent repository are reported with paths relative to the repository root.