feat: add config.INHERIT_ENV to pass local process env vars to all op… (#1677)

Author: maisim

docs/inventory-data.rst

@@ -158,3 +158,21 @@ External Sources for Data
 -------------------------
 
 Because pyinfra is configured in Python, you can pull in data from pretty much anywhere just using other Python packages.
+
+Environment Variables
+~~~~~~~~~~~~~~~~~~~~~
+
+``config.INHERIT_ENV`` lets you forward specific environment variables from the machine running pyinfra to all remote operations. This is useful for tools that authenticate via environment variables (SOPS, cloud CLIs, etc.):
+
+.. code:: python
+
+    # deploy.py
+    from pyinfra import config
+
+    config.INHERIT_ENV = ["SOPS_AGE_KEY_FILE", "AWS_PROFILE", "GITLAB_TOKEN"]
+
+The priority for environment variables passed to operations is (lowest to highest):
+
+1. ``config.INHERIT_ENV`` — inherited from the caller's ``os.environ``
+2. ``config.ENV`` — explicitly set globally in the deploy script
+3. ``_env`` per-operation argument — overrides for a single operation

src/pyinfra/api/arguments.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -85,7 +86,8 @@ class ConnectorArguments(TypedDict, total=False):
 
 
 def generate_env(config: "Config", value: dict) -> dict:
-    env = config.ENV.copy()
+    env = {key: os.environ[key] for key in config.INHERIT_ENV if key in os.environ}
+    env.update(config.ENV)
     env.update(value)
     return env
 

src/pyinfra/api/config.py

@@ -4,7 +4,7 @@
     import importlib.metadata as importlib_metadata  # type: ignore[no-redef]
 
 from os import path
-from typing import Iterable, Optional, Set
+from typing import Iterable, Optional, Sequence, Set
 
 from packaging.markers import Marker
 from packaging.requirements import Requirement
@@ -63,6 +63,9 @@ class ConfigDefaults:
     RETRY: int = 0
     # Delay in seconds between retry attempts
     RETRY_DELAY: int = 5
+    # List of environment variable names to inherit from the local process environment.
+    # These are passed to every shell command, with lower priority than config.ENV.
+    INHERIT_ENV: Sequence[str] = ()
 
 
 config_defaults = {key: value for key, value in ConfigDefaults.__dict__.items() if key.isupper()}