Skip to main content

env

The env global is a read-only dictionary of the environment values a step declares for its script. It holds exactly the inputs you wrote in the step's env: map, after templates are resolved. Use os.getenv when the script needs an inherited environment value.

Usage​

env["NAME"]
env.get("NAME", "default")

Contents​

  • Keys and values are strings.
  • The dictionary contains the entries of the step's env: map, with templates rendered. Nothing else is added.
  • The dictionary is frozen. Assigning to it, such as env["REGION"] = "x", fails with cannot insert into frozen hash table.
  • A standalone script has no step, so env is empty.

Changes made with os.setenv do not modify this dictionary. Use os.environ for a frozen snapshot of the effective process environment.

The dictionary is not a copy of the process environment, so "HOME" in env is False unless the step declares HOME. Programs started with exec.run and the other process-running functions inherit the effective execution environment on their own, including authentication and command environment settings. Pass extra variables to one call with that function's env argument. Use os.getenv to read a value from the effective execution environment without adding it to this dictionary.

Dictionary methods​

The usual dictionary operations apply:

env[name]
The value of a declared input. A name that is not declared fails with a key error.
env.get(name, default)
The value of a declared input, or default when it is not declared. Without default, the fallback is None.
name in env
Whether the input is declared.
env.keys(), env.items(), len(env)
Enumerate the declared inputs.

Examples​

Read declared inputs in a custom command​

commands:
  - name: show-env
    description: Print declared env
    steps:
      - name: show
        type: script
        interpreter: starlark
        env:
          REGION: us-east-2
          NAME: "{{ \"demo\" | upper }}"
        script: |
          print(env["REGION"], env["NAME"])
          print(env.get("MISSING", "default-value"))
          print(sorted(env.keys()))
          print("HOME" in env)
us-east-2 DEMO
default-value
["NAME", "REGION"]
False

Choose a value from an input in a workflow​

workflows:
  deploy:
    steps:
      - name: choose
        type: script
        interpreter: starlark
        env:
          REGION: us-east-1
        script: |
          output = "blue" if env["REGION"] == "us-east-1" else "green"

Declare the input once and use it in parallel tasks​

workflows:
  regions:
    steps:
      - name: fanout
        type: script
        interpreter: starlark
        env:
          REGION: us-east-1
        script: |
          def api():
              return {"service": "api", "region": env["REGION"]}

          def worker():
              return {"service": "worker", "region": env["REGION"]}

          output = steps.parallel(functions = [api, worker])

The dictionary is already frozen, so parallel tasks read it safely.

Pass a value to a child process​

result = exec.run(
    ["printenv", "TARGET_REGION"],
    env = {"TARGET_REGION": env.get("REGION", "us-east-1")},
    output = "capture",
)

Related​