Shrub.py

3.10.0 · active · verified Sat Apr 11

Shrub.py is a Python library designed for programmatically building Evergreen project configurations. It allows users to define complex CI/CD task graphs and build variants using Python objects, which can then be serialized into the JSON format required by Evergreen. The library is actively maintained, with its latest version being 3.10.0, released in April 2025.

Warnings

breaking Shrub.py uses versioned import paths (e.g., `shrub.v3`). Upgrading to a new major version of the library may require updating import statements to reflect the new API version (e.g., from `shrub.v2` to `shrub.v3`).
Fix: Review the official `shrub.py` documentation and release notes for breaking changes and update import paths (e.g., `from shrub.v2...` to `from shrub.v3...`) and object constructors accordingly.
gotcha The structure and available fields for Evergreen configurations are dictated by the Evergreen API itself. Errors in generated JSON often stem from mismatches with the expected Evergreen schema, rather than `shrub.py` library issues.
Fix: Always consult the official Evergreen documentation for the precise structure and valid values for project configurations, tasks, and commands when encountering issues with the generated JSON.

Install

pip install shrub-py Install with pip

Imports

EvgTask
```
from shrub.v3.evg_task import EvgTask
```
The library's API is versioned under the `shrub.vX` namespace. Always import from the specific major version (e.g., `v3`) to ensure compatibility with the desired Evergreen API version.
ShrubService
```
from shrub.v3.shrub_service import ShrubService
```
Similar to other components, `ShrubService` is part of the versioned API. Ensure you import from the correct `vX` namespace.

Quickstart

This quickstart demonstrates how to define an Evergreen project configuration using shrub.py. It creates multiple parallel tasks, groups them under a display task, associates them with a build variant, and then generates the corresponding Evergreen JSON output. This example illustrates task definition, command execution with variables, and task dependencies.

from shrub.v3.evg_task import EvgTask, EvgTaskDependency
from shrub.v3.evg_build_variant import BuildVariant, DisplayTask
from shrub.v3.evg_command import FunctionCall
from shrub.v3.evg_project import EvgProject
from shrub.v3.shrub_service import ShrubService
import json

n_tasks = 3

def define_task(index):
    name = f"my_test_task_{index}"
    return EvgTask(
        name=name,
        commands=[
            FunctionCall(func="do_setup_function"),
            FunctionCall(
                func="run_test_script",
                vars={
                    "param1": f"value_{index}",
                    "param2": "static_value"
                }
            ),
            FunctionCall(func="do_teardown_function")
        ],
        depends_on=[EvgTaskDependency(name="compile_job")]
    )

tasks = [define_task(i) for i in range(n_tasks)]
display_task = DisplayTask(
    name="full_test_suite",
    execution_tasks=[t.name for t in tasks]
)

variant = BuildVariant(
    name="linux-build",
    tasks=[],
    display_tasks=[display_task]
)

project = EvgProject(buildvariants=[variant], tasks=tasks)

# Generate the Evergreen JSON configuration
evergreen_config_json = ShrubService.generate_json(project)

print(json.dumps(evergreen_config_json, indent=4))

view raw JSON →