Vivarium Build Utils
Vivarium Build Utils contains shared build utilities for Simulation Science projects.
Supported Python versions: 3.11, 3.12, 3.13
You can install vivarium-build-utils from PyPI with pip:
pip install vivarium-build-utilsor build it from source by cloning the monorepo and installing this package:
git clone https://github.com/ihmeuw/vivarium-suite.git
cd vivarium-suite/libs/build-utils
conda create -n ENVIRONMENT_NAME
pip install -e .Overview
This repository provides:
`vars/`: Jenkins shared library functions for continuous integration pipelines
`resources/`: Shared Makefiles and build scripts for consistent build processes
Note: for help with the Make targets available to any environment with this repository installed, run make help in the terminal.
Monorepo support
vivarium-build-utils supports both standalone repos and monorepos where many packages live under libs/<pkg>/. Standalone repos keep working with no changes; the sections below describe what’s needed for a monorepo.
Top-level Jenkinsfile (provisioner)
The monorepo’s root Jenkinsfile calls monorepo() to provision a Multibranch Pipeline for each per-package Jenkinsfile. Run this on the default branch only:
@Library('vivarium_build_utils') _
monorepo(
jenkinsfiles: [
'libs/core/Jenkinsfile',
'libs/public-health/Jenkinsfile',
],
// Jenkins credential ID for the GitHub App. Required, no default; vbu
// stays org-agnostic so the literal UUID lives next to the org context.
githubCredentialsId: 'fad62062-b1f4-447b-997f-005d6b1ea41e',
folderPrefix: 'Public', // optional, defaults to "Public"
)
The provisioned pipelines land under <folderPrefix>/<repo>/libs/<pkg>/.
Per-package Jenkinsfile
Each libs/<pkg>/Jenkinsfile calls reusable_pipeline() the same way a standalone repo would, with one new argument:
@Library('vivarium_build_utils') _
reusable_pipeline(
test_types: ['unit', 'integration'],
deployable: true,
env_reqs: 'ci_jenkins', // pyproject.toml extra to install
)
env_reqs selects which [project.optional-dependencies] extra make install pulls in. Omit it (or leave empty) on standalone repos to keep base.mk’s default of dev.
Deployable callers (deployable: true) can also pass github_credentials_id: '<jenkins-credential-id>' to override the git credential used at deploy time for pushing the release tag. When omitted, the deploy stage falls back to the credential configured on the Multibranch Pipeline’s branch source, which is the right default for most repos.
Tag prefix
The TAG_PREFIX environment variable controls both make tag-version and make validate-tag. It must be set consistently in both targets, or validate-tag will silently look at the wrong set of tags.
Standalone repos: leave unset. Tags are v<X.Y.Z>.
Monorepo libs: set TAG_PREFIX=vivarium-<lib>- (e.g. vivarium-core-). Tags become vivarium-<lib>-v<X.Y.Z>.
Release workflows that invoke make validate-tag or make tag-version should export TAG_PREFIX before running them.
Fetching from internal Artifactory
IHME_PYPI defaults to the internal Artifactory URL and is woven into EXTRA_INDEX_FLAGS for make install. Override it to empty (make install IHME_PYPI=) in environments that can’t reach IHME’s network (e.g. GitHub Actions runners). make deploy-package-artifactory requires a non-empty IHME_PYPI and is Jenkins/internal-only.
Cross-library PRs
A single PR can modify several interdependent monorepo libraries, including bumping one and consuming the new version of another even though the upstream’s dependency on it still resolves against PyPI (where the new version isn’t released yet). make install CHANGED_LIBS="<lib1> <lib2> ..." opts a build into in-tree resolution where any CHANGED_LIBS (libraries whose source changed in the PR) that are also (1) reachable from the package being built and (2) whose pending CHANGELOG.rst version satisfies the dependents’ pins are installed editably from local source (at the pending version) with a single uv invocation. Unchanged dependencies still resolve from PyPI.
CHANGED_LIBS is a no-op when empty, so single-package installs are unaffected.
The GitHub Actions CI and release workflows wire this automatically.
When a build deploys
This applies to repos that pass deployable: true; monorepo libs release through GitHub Actions instead and never reach the Jenkins deploy stage.
Only a build Jenkins started because it found a new commit deploys on its own. If you do want to release from a build you started by hand, set FORCE_DEPLOY; that is also how to redrive a deploy that failed partway through.
A deploy requires all of:
deployable: true
the main branch
a deployable change in the tip commit
a new-commit build or FORCE_DEPLOY
a version update in CHANGELOG.rst
1 maintainer
Release files for vivarium-build-utils 4.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vivarium_build_utils-4.8.0.tar.gz | 84.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vivarium_build_utils-4.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 125.4 kB
Release files / vivarium_build_utils-4.8.0.tar.gz
| Download URL | vivarium_build_utils-4.8.0.tar.gz |
|---|---|
| Size | 84.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c88d5c3360fdacd81285a7bfe0f82bebe5b434f031d29255694d793c28cf3023
|
|
BLAKE2b-256 checksum How to use checksums |
8ef9e20fbda1c949c4602a2ca31adc499382ad644ff2222d59235a64337f10d5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / vivarium_build_utils-4.8.0-py3-none-any.whl
| Download URL | vivarium_build_utils-4.8.0-py3-none-any.whl |
|---|---|
| Size | 41.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8c556647be0ee80ac6bd8c47fdab4a75b5f42269682d3b495ea316243705465f
|
|
BLAKE2b-256 checksum How to use checksums |
fa49935e03cabb0cd32525f24e0a5ca00596288d65d0bf5ecc79ea62684a1f18
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency log
