4.4.2 RunEnvironmentInfo

RunEnvironmentInfo is the provider a custom executable or test rule returns when the launched program needs environment variables. It is part of the runtime contract introduced in 4.2.6 Executable & Test Rules: DefaultInfo tells Bazel what to launch and which runfiles to stage, while RunEnvironmentInfo tells Bazel which environment entries to add when that executable runs under bazel run or bazel test.¹

The Launch Environment Is A Provider Contract

The provider has two fields. environment is a dictionary of exact variable names and values. Those values are made available when the target is executed as a test or through bazel run.² inherited_environment is a list of variable names whose values Bazel takes from the shell environment at launch time.³

def _tool_test_impl(ctx):
    executable = ctx.actions.declare_file(ctx.label.name)
    runfiles = ctx.runfiles(files = [ctx.file.config])

    ctx.actions.write(
        output = executable,
        content = "#!/usr/bin/env bash\nexec \"$@\"\n",
        is_executable = True,
    )

    return [
        DefaultInfo(executable = executable, runfiles = runfiles),
        RunEnvironmentInfo(
            environment = {
                "MY_RULE_MODE": ctx.attr.mode,
                "MY_RULE_CONFIG": ctx.file.config.short_path,
            },
            inherited_environment = [
                "MY_RULE_DEBUG_TOKEN",
            ],
        ),
    ]

This is not a way to pass inputs to the action that creates the executable. The implementation function still runs during analysis, and build actions still need declared inputs, tools, arguments, and action environment on their own contract. Keep RunEnvironmentInfo for the process Bazel launches after the target has been built. Keep action execution settings in 4.4.3 Action Execution Contract.

Prefer Explicit Values

For production rules, environment should be the normal path. It makes the rule's runtime promise visible in analysis: the variable name is stable, the value comes from rule attributes or other declared analysis-time data, and downstream users can reason about the behavior without knowing the developer's laptop state.

Good examples are toggles derived by the rule, paths that the launcher understands, and mode names derived from attributes. If the value names a runtime file, pass a runfiles-relative path and make sure the file is also present in DefaultInfo(runfiles = ...). An environment variable that points at a missing file is just a delayed runfiles bug. 4.2.5 DefaultInfo & Runfiles explains how the runtime file enters runfiles.

inherited_environment is different. If a variable appears in both fields, the inherited shell value wins when it is set.⁴ That makes inheritance a deliberate escape hatch, not a convenience default. It is most useful for tests that truly need a host-specific value, because bazel test normally runs tests in a hermetic environment. The provider documentation warns that hardcoding this kind of host dependency can surprise users and can expose sensitive information.⁵

Tests Are More Sensitive Than Run Targets

bazel run already forwards the outer environment, so inheriting variables through RunEnvironmentInfo is mainly about test rules.⁶ Tests have a much stricter launch contract: the Test Encyclopedia specifies an initial environment block with variables such as TEST_TMPDIR, TEST_SRCDIR, TEST_WORKSPACE, HOME, PATH, and LC_CTYPE (which may be unset or C.UTF-8), and it treats writable locations and runfiles access as part of the test's hermetic execution model.⁷

That is why a test rule should not casually inherit HOME, PATH, cloud credentials, or locale variables. Each inherited variable becomes part of what the test observes but not necessarily part of what a reviewer sees in the BUILD file. If the test result can change when the caller's shell changes, the test caching model from 1.2.1 Test Caching becomes harder to trust, and the hermeticity principle from 2.3.1 Hermeticity is no longer just a build-action concern.

When a developer needs to inject a value for one invocation, prefer the CLI mechanism. --test_env=NAME=value injects an explicit value into each test environment. --test_env=NAME inherits the value from the shell used to start bazel test.⁸ The provider documentation still recommends avoiding that flag when possible and populating the environment explicitly, but it is better as an invocation-level override than baking host inheritance into a reusable rule.⁹

Do Not Reconstruct The Whole Environment

Rule authors can inspect ctx.configuration.test_env, which is the dictionary of user-specified test variables from --test_env options.¹⁰ The API reference marks it with a blunt warning against relying on it, because it is not the complete environment.¹¹ Treat that field as a narrow compatibility signal, not as a source from which to rebuild the test process environment.

The same boundary matters for bazel run. The user manual says bazel run is similar to building and then invoking the binary, but not identical. Non-test binaries run with their current working directory in the binary's runfiles tree, and Bazel also provides BUILD_WORKSPACE_DIRECTORY, BUILD_WORKING_DIRECTORY, BUILD_ID, and BUILD_EXECROOT.¹² If bazel run executes a test binary, Bazel makes a good-faith attempt to approximate the test environment, but the manual explicitly notes that the emulation is not perfect.¹³

Those details are reasons to avoid clever environment synthesis inside the rule. The rule should declare only the environment entries it defines. Bazel and the test runner provide the rest of the launch environment.

The mini-ruleset's glyph_test is a complete narrow use: it returns one explicit RunEnvironmentInfo(environment = ...) value for the test runner and keeps the binary plus runtime files in DefaultInfo.runfiles.