This Repository is NOT a supported MongoDB product

This repo is meant for MongoDB drivers to bootstrap their Evergreen configuration files. It contains set of scripts for tasks that most drivers will need to perform, such as downloading MongoDB for the current platform, and launching various topologies.

For maintenance of this repo see the Contributing Guide. If adding a new feature, follow the New Features guidance.

The bundled .evergreen/config.yml file contains a suggested template for drivers to use. This file can either be taken and used as is, or used as a recipe to copy&paste from.

It is recommended to copy the entire directory and modify the following scripts:

• install-dependencies.sh - Install any platform dependencies not currently available on Evergreen
• run-tests.sh - How to run the test suite
• compile.sh - Configure any alternative environment routes
• compile-unix.sh - Instructions to run the compile stage on *nix
• compile-windows.sh - Instructions to run the compile stage on Windows
• make-docs.sh - Instructions how to compile the driver docs
• make-release.sh - Instructions how to package and release the driver

The normal matrix (e.g. all tasks with the exception on those in the ** Release Archive Creator buildvariant) runs the following two shell scripts:

• The install-dependencies.sh file is always executed by all tasks.
• The run-tests.sh is run by all tasks, except for the ** Release Archive Creator.

The ** Release Archive Creator buildvariant is special, and does not run the "standard test matrix", but in stead runs the following:

• The compile*.sh is executed by the release-compile and release-compile-cmake tasks. These are no commonly used by drivers, so feel free to ignore.
• The make-docs.sh is executed by the make-docs task
• The make-release.sh is executed by the make-release-archive task

See also: https://evergreen.mongodb.com/waterfall/drivers-tools

Requesting MONGODB_VERSION=latest or latest-build downloads an unpublished nightly build from a private S3 bucket, rather than the old public downloads.mongodb.com/downloads.10gen.com HTTP hosts. mongodl.py handles authentication itself, using whatever AWS identity is already active. No separate setup script or manually-exported secrets are required. In Evergreen, this just needs an ec2.assume_role step for drivers_test_secrets_role before the download step (wired into the global pre block, which assumes the role for every task). Locally, it needs a working AWS identity: one with direct access to the origin-mongodb-server-latest bucket, or a profile that can reach the drivers/devprod-release-infrastructure AWS Secrets Vault and assume the roles it names (the same setup documented in Secrets Handling). Any version other than latest/latest-build (e.g. latest-stable, or a pinned version like 8.0) is unaffected and needs no AWS access.

As a migration fallback, if AWS credentials for the private server artifacts cannot be resolved — either none are available, or the ambient identity is not authorized to reach the bucket or the vault — mongodl falls back to the old public downloads.10gen.com download link and emits a prominent FALLBACK: warning in the logs. The legacy link is deprecated and will be removed in a future release, so treat that warning as a signal to configure AWS credentials as described above (see the DRIVERS-3628 migration guide).

latest/latest-build archives are also signature-verified: mongodl downloads the detached GPG signature published next to the artifact and verifies it against the MongoDB release signing keys, pinned by fingerprint and fetched at verification time from pgp.mongodb.com (the master-nightly builds are signed by the MongoDB 9 release key and the legacy-host builds by the 8.0 release key). A bad signature — or a signature made by any other key — fails the download. If a signature was not published for the artifact (stable-branch staging builds may not be signed yet), or the host has no gpg binary, mongodl only logs a warning and the download continues. Published builds and other version selectors are unaffected and keep using the SHA-256 checksums from full.json.

run-mongodb.sh (the mongodb-runner entry point for local dev and the GitHub Actions composite action) defaults to latest-stable. The GitHub Action also maps latest to latest-stable since runners typically lack AWS credentials; elsewhere an explicit MONGODB_VERSION=latest downloads the nightly build. Under --local-atlas the default stays latest, which is the mongodb-atlas-local Docker image tag.

This repository includes a metadata file for GitHub Actions to allow downloading MongoDB and launching topologies from a GitHub Action Workflow. To use this action, use the following template:

    steps:
      # [...]
      - id: setup-mongodb
        uses: mongodb-labs/drivers-evergreen-tools@master
        # Set configuration
        with:
          version: ${{ matrix.mongodb-version }}

The following inputs exist:

These correspond to the respective environment variables that are passed to run-orchestration.sh.

The example above tracks master. To pin a published version instead, use a release tag such as mongodb-labs/drivers-evergreen-tools@v1.0.0. See Releasing for how those versions are cut.

After the cluster is started, its URI is exposed via the cluster-uri output. In addition, the action also exposes the path to crypt_shared via the crypt-shared-lib-path output, unless the installation was not requested or failed. This configuration snippet environment variables with the cluster URI and crypt_shared lib path returned from the setup-mongodb workflow step when running tests:

    steps:
      # [...]
      - name: "Run Tests"
        run: "run-tests.sh"
        env:
          MONGODB_URI: ${{ steps.setup-mongodb.outputs.cluster-uri }}
          CRYPT_SHARED_LIB_PATH: ${{ steps.setup-mongodb.outputs.crypt-shared-lib-path }}

There are two options for running a MongoDB server configuration. One is to use docker. The other is to run ./evergreen/run-orchestration.sh locally. For convenience, you can run make run-server and make stop-server to start and stop the server(s).

For example:

TOPOLOGY=replica_set MONGODB_VERSION=7.0 make run-server

You can also run: make run-local-atlas to run a local atlas server in a container.

See run-orchestration.sh for the available environment variables. Run bash ./evergreen/run-orchestration.sh --help for usage of command line flags.

In order to use custom certificates in your server, set the following environment variables:

export TLS_CERT_KEY_FILE=<path-to>/client.pem
export TLS_PEM_KEY_FILE=<path-to>/server.pem
export TLS_CA_FILE=<path-to>/ca.pem

Orchestration can start clusters with the server's OpenTelemetry file exporter enabled (opt-in via OTEL=1), for the trace-context propagation prose tests (DRIVERS-3454). See .evergreen/orchestration/README.md for usage, requirements, and driver integration guidance.

The start-orchestration.sh script can be used directly as a way to start the orchestration server without downloading binaries or starting a local server. You are still responsible for having a directory containing the MongoDB binaries in the default MONGODB_BINARIES folder or setting MONGODB_BINARIES to the appropriate folder.

See run-orchestration.sh for the available environment variables.

Run bash ./evergreen/start-orchestration.sh --help for usage of command line flags.

As part of DRIVERS-3335 we are migrating away from using mongo-orchestration and its associated scripts (run-orchestration.sh, stop-orchestration.sh, and start-orchestration.sh).

We are instead using @mongodb-js/mongodb-runner using the new script run-mongodb.sh script with either start or stop as the argument, e.g.:

TOPOLOGY=replica_set bash .evergreen/run-mongodb.sh start

The mongodb-runner cli is maintained by the DevTools team in the devtools-shared repo.

Sometimes you'll need to run tests against a specific version, such as "7.0", and to do that you can use the VERSION env var.

VERSION=7.0 TOPOLOGY='replica_set' bash .evergreen/run-orchestration.sh

Older versions of MongoDB may not have arm64 macOS binaries, so you may also need to install the x86_64 binary (note: this will use Rosetta to run the binary):

VERSION=4.2 ARCH=x86_64 TOPOLOGY='replica_set' bash .evergreen/run-orchestration.sh

The named versions that we support are:

• latest - the most recent server build from Evergreen (e.g. 8.3.0-alpha1-8-g9a81264)
• rapid - the most recent published server minor release, including release candidates (e.g. 8.2.0rc1 or 8.3.2, but not 8.0.1).
• latest-stable - the most recently published stable server release, excluding release candidates (e.g. 8.3.4)
• v6.0-perf - the pinned 6.x server version for performance testing
• v8.0-perf - the pinned 8.x server version for performance testing

You may encounter this error if Rosetta isn't properly configured on your system.

OSError: [Errno 86] Bad CPU type in executable: '.../node-mongodb-native/drivers-evergreen-tools/mongodb/bin/mongod'

To fix it, simply run:

softwareupdate --install-rosetta

For convenience, there are two scripts that can be used for setup and teardown of assets and services used by drivers-evergreen-tools.

$DRIVERS_TOOLS/.evergreen/setup-test.sh will handle common setup actions that have previously been spread through multiple pre: tasks in drivers.

$DRIVERS_TOOLS/.evergreen/teardown-test.sh will clean up common assets and services. This script will also collect all logs files recursively found in the ${DRIVERS_TOOLS} directory into a single ${DRIVERS_TOOLS}/.evergreen/test_logs.tar.gz file for convenient uploading.

Subfolders that have setup and teardown requirements are encouraged to also provide setup-test.sh and teardown-test.sh.

NOTE: The subfolder setup/teardown scripts requires users to have configured support for Secrets Handling.

See the Secrets Handling readme for more information on how secrets are managed locally and on on Evergreen.

We make some of our Python scripts available as self-contained clis that do not require setting up a Python virtual environment. For example, after running .evergreen/setup.sh you can run the resulting .evergreen/mongodl, .evergreen/mongosh-dl and .evergreen/socks5srv scripts directly.

This repo supports the use of .env files, which can be placed in $DRIVERS_TOOLS and in the sub-directories. The script will first read $DRIVERS_TOOLS/.env if it exists, and then $SCRIPT_DIR/.env if it exists, to give the local file higher precedence. This pattern can be used to replace the use of legacy ${PREPARE_SHELL} invocations in a shell.exec Evergreen command, enabling the use of subprocess.exec instead.

This repo also contains a Python package for use in scripts that generate Evergreen config files from Python dicts. See evergreen_config_generator/README.