Add extra-env input to propagate global env variables

Introduce a new `extra-env` input for passing environment variables as space-separated KEY=VALUE pairs to all workflow steps. These variables are treated as defaults and do not override existing step-specific values.

Author: mkaput

.github/workflows/experiment.yml

@@ -25,6 +25,10 @@ on:
         description: "Custom report name"
         required: false
         type: string
+      extra_env:
+        description: "Extra env (space-separated KEY=VALUE pairs passed to all steps)"
+        required: false
+        type: string
       notify_team:
         description: "Notify team (if you want the whole team to check the run)"
         type: boolean
@@ -90,13 +94,16 @@ jobs:
           echo "sandbox-digest=$DIGEST" >> $GITHUB_OUTPUT
 
       - name: Create plan
+        env:
+          EXTRA_ENV: ${{ inputs.extra_env }}
         run:
           ./maat plan
           --workspace "${{ inputs.workspace }}"
           --pull "${{ env.SANDBOX_DIGEST }}"
           --output maat-plan.json
           --partitions ${{ env.PARTITIONS_COUNT }}
           ${{ inputs.report_name && format('--report-name "{0}"', inputs.report_name) }}
+          ${{ inputs.extra_env && '--extra-env "$EXTRA_ENV"' }}
 
       - name: Generate partition array
         id: generate-partitions

src/maat/__init__.py

@@ -208,6 +208,12 @@ def cli() -> None:
     default=None,
     help="Override report name.",
 )
+@click.option(
+    "--extra-env",
+    type=str,
+    default=None,
+    help="Extra environment variables passed to all steps, e.g. 'SCARB_INCREMENTAL=0 CAIRO_LS_LOG=debug'.",
+)
 @load_workspace
 @tool_versions(optional_if_pull=True)
 @load_sandbox_image
@@ -218,6 +224,7 @@ def run_local(
     sandbox_image: Image,
     jobs: int | None,
     report_name: str | None,
+    extra_env: str | None,
 ) -> None:
     log(f"🧪 Running experiment within workspace: {workspace}")
 
@@ -227,6 +234,7 @@ def run_local(
         partitions=1,
         docker=docker,
         report_name=report_name,
+        extra_env=extra_env,
     )
 
     reporter = Reporter(plan)
@@ -505,6 +513,12 @@ def gc_reports() -> None:
     default=None,
     help="Override report name.",
 )
+@click.option(
+    "--extra-env",
+    type=str,
+    default=None,
+    help="Extra environment variables passed to all steps, e.g. 'SCARB_INCREMENTAL=0 CAIRO_LS_LOG=debug'.",
+)
 @load_workspace
 @tool_versions
 @load_sandbox_image
@@ -516,13 +530,15 @@ def plan(
     output: Path,
     partitions: int,
     report_name: str | None,
+    extra_env: str | None,
 ) -> None:
     plan = prepare_plan(
         workspace=workspace,
         sandbox=sandbox_image,
         partitions=partitions,
         docker=docker,
         report_name=report_name,
+        extra_env=extra_env,
     )
 
     json_data = plan.model_dump_json(indent=2) + "\n"

src/maat/runner/planner.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+import shlex
 
 from maat.utils.log import track
 from python_on_whales import DockerClient, Image
@@ -67,6 +68,7 @@ def prepare_plan(
     partitions: int,
     docker: DockerClient,
     report_name: str | None = None,
+    extra_env: str | None = None,
 ) -> Plan:
     scarb, foundry = tool_versions(sandbox, docker)
 
@@ -77,6 +79,13 @@ def prepare_plan(
             test = Test(name=project.name, rev=project.fetch_rev(), steps=steps)
             tests.append(test)
 
+        # Parse and merge extra environment variables into every step
+        if extra_env_map := _parse_extra_env(extra_env):
+            for test in tests:
+                for step in test.steps:
+                    # Do not override per-step variables; treat extra vars as defaults
+                    step.env = {**extra_env_map, **(step.env or {})}
+
         suite = TestSuite(tests=tests)
 
     # Explicitly provided report name takes precedence over workspace settings.
@@ -108,3 +117,22 @@ class _PlanningReportNameGenerationContext(ReportNameGenerationContext):
     workspace: str
     scarb: str
     foundry: str
+
+
+def _parse_extra_env(extra_env: str | None) -> dict[str, str] | None:
+    """Parse space-separated KEY=VALUE pairs into a dict.
+
+    Uses shlex.split to properly handle quotes (e.g., KEY="value with spaces").
+    Returns None if no valid pairs are found.
+    """
+    if not extra_env:
+        return None
+
+    result: dict[str, str] = {}
+    for token in shlex.split(extra_env):
+        if "=" in token:
+            key, value = token.split("=", 1)
+            if key:
+                result[key] = value
+
+    return result or None