Build Environment

The BuildEnv helper in the mr library gives you a standardized way to read information about the current build environment, such as:

the git commit hash
the current branch or tag
the repository URL, owner, and name
whether versioned models should be generated or not for this build
the build number

You can use it:

Locally, when running builds via MakerRepo CLI, or
On MakerRepo.com, where the same information is exposed via environment variables for your repository builds.

In both cases you use the same Python API: BuildEnv.

Importing `BuildEnv`

from mr import BuildEnv

BuildEnv is a frozen dataclass that captures key fields of the build environment (with their corresponding environment variables):

Field	Env var	Description
`build_id`	`MR_BUILD_ID`	Unique identifier (UUID) of the build job, if provided by MakerRepo.com or CI.
`build_number`	`MR_BUILD_NUMBER`	Numeric build/job number, typically monotonically increasing in CI. This is usually only set in CI, but you can set it locally so `makerrepo-cli` can read it while running commands.
`build_version`	`MR_BUILD_VERSION`	Explicit version string to use for the build; if set, it overrides other version sources in `get_build_version()`.
`versioned_model_enabled`	`MR_VERSIONED_MODEL_ENABLED`	Whether versioned models are enabled. It defaults to `True` in most cases; set this to `0`, `false`, or `no` when you want to skip adding version marks to models and save some compute time.
`git_commit`	`MR_GIT_COMMIT`	Git commit hash used for the build.
`git_ref`	`MR_GIT_REF`	Full git ref, such as `refs/heads/master` or `refs/tags/v1.2.3`.
`git_ref_name`	`MR_GIT_REF_NAME`	Short ref name (e.g. `master`, `feature-x`, `v1.2.3`).
`repository_name`	`MR_REPOSITORY_NAME`	Repository name (e.g. `open-source-robot`).
`repository_username`	`MR_REPOSITORY_USERNAME`	Owner/user or organization of the repository.
`repository_url`	`MR_REPOSITORY_URL`	Full git remote URL for the repository.

These variables are:

Set automatically by MakerRepo.com CI when your repository is built on the platform or in your pipeline.
Read locally by MakerRepo CLI if they are set; otherwise, the CLI (and BuildEnv.from_local_git_repo()) will fall back to discovering the same information from your current local git repository.

Creating a `BuildEnv`

From environment only

env = BuildEnv.from_env()

This reads only the MR_… environment variables and does not touch git. It is useful when you know your CI (or MakerRepo.com) will set everything you need.

From local git repo (with env overrides)

env = BuildEnv.from_local_git_repo()

This is the recommended way to get a build environment in most MakerRepo projects:

It first reads any MR_… environment variables (so CI or MakerRepo.com can override values).
For anything not provided, it falls back to your local git repository:
git_commit from git rev-parse HEAD
git_ref and git_ref_name from the current branch or tag
repository_url from git remote get-url
repository_username and repository_name parsed from the remote URL

This makes your code behave consistently both locally and on MakerRepo.com, while still allowing CI-only or user-provided fields (such as a build number) to be set explicitly via environment variables when needed.

Getting a human‑readable build version

BuildEnv also provides a helper for choosing a sensible version string for a build:

version = env.get_build_version()

The precedence is:

If build_version is set (e.g. MR_BUILD_VERSION), use that.
If the current git ref is a tag (e.g. refs/tags/v1.2.3), use the tag name.
If build_number is set (e.g. from CI), use that.
If git_commit is set, use the first 4 characters of the commit hash (configurable).
Otherwise, fall back to "unknown".

This is especially helpful for things like embossing a version mark on a prototype part or including a version string in metadata.

Example: using BuildEnv in an artifact

from mr import artifact, BuildEnv


@artifact(short_desc="Example part with build metadata")
def example_part():
    env = BuildEnv.from_local_git_repo()

    # Decide whether to use versioned models for this build
    if not env.versioned_model_enabled:
        # Build a simple model without any version mark
        model = build_model_without_version_mark()
        return model

    version = env.get_build_version()
    model = build_model_with_version_mark(version)
    return model

Here:

Locally, from_local_git_repo() derives information from your git repo (and any MR_… variables you set).
On MakerRepo.com, the same call uses the environment variables provided by the platform, so the build version and metadata match the build job.

Example: branch builds vs release tags

Using the build environment to add a version mark is the most common use case, but building a model based on different criteria is a powerful feature. The real value of Manufacturing as Code is not just managing CAD models with Git as the version control system, but thinking about how to optimize the workflow as you would when building software. For example, say you want to build a model that has a version mark only when the build is from a branch, not a tag.

from mr import artifact, BuildEnv


@artifact(short_desc="Part that distinguishes branch builds from releases")
def release_aware_part():
    env = BuildEnv.from_local_git_repo()

    # If we are building from a tag, treat this as a release build:
    # use the tag as the version and do not add a version mark to the model.
    is_tag_build = env.git_ref and env.git_ref.startswith("refs/tags/")
    if is_tag_build:
        return build_clean_release_model()

    # Otherwise, build from branch + optional build number (e.g. CI build)
    branch_name = env.git_ref_name or "unknown-branch"
    build_number = env.build_number
    if build_number is not None:
        version_mark = f"{branch_name}#{build_number}"
    else:
        version_mark = branch_name

    return build_model_with_version_mark(version_mark)