Add support for passing environment variables to workflows

[danielibarrola]

Summary

This PR introduces the ability to pass custom environment variables to GitHub Action workflows triggered by the Culprit Finder. This is particularly useful for workflows that require specific configurations to run successfully during the bisection process.

Changes

• CLI Enhancement: Added a new --env argument to the culprit-finder command. It accepts multiple KEY=VALUE pairs.
• Environment Variable Parsing: Implemented a helper function _parse_env_vars in cli.py to convert CLI input into a dictionary.
• Workflow Integration: Updated CulpritFinder to accept env_vars. These variables are serialized into a compact JSON string and passed to the workflow via the json_vars input.
• Testing:
  • Added unit tests in test_cli.py to verify correct parsing of the --env flag.
  • Added unit tests in test_culprit_finder.py to ensure json_vars are correctly formatted and passed to the GitHub client.
• Documentation: Updated the README.md with usage for the new --env flag.

Example Usage

culprit-finder \
  --repo owner/repo \
  --start a1b2c3d \
  --end e5f6g7h \
  --workflow build.yml \
  --env DEBUG=true TIMEOUT=60

[danielibarrola]

Test results

Verified that custom environment variables are correctly parsed by the CLI, passed to the CulpritFinder core logic, and injected into the GitHub workflow dispatch.

Verification Run

Executed the tool against jax-fork workflow using the new --env flag to pass debugging and timeout parameters:

culprit-finder https://github.com/google-ml-infra/jax-fork/actions/runs/21685189508 \
  --env DEBUG=true TIMEOUT=60

Observations:

• Variable Injection: Confirmed that DEBUG=true and TIMEOUT=60 were correctly serialized into the json_vars input.
• Job Execution: The target job successfully received and printed these variables, as seen in this [Workflow Job Log]
• Successful Bisection: The tool successfully identified the culprit commit (d263df9e) after testing the midpoint commits with the provided environment.

Click to view full execution logs

culprit-finder https://github.com/google-ml-infra/jax-fork/actions/runs/21685189508 --env DEBUG=true TIMEOUT=60
2026-02-04 13:25:47,223 - INFO - Initializing culprit finder for google-ml-infra/jax-fork
2026-02-04 13:25:47,224 - INFO - Start commit: 1135c51e845e907e430fddbbb51d5dd5dde8cbe9
2026-02-04 13:25:47,224 - INFO - End commit: 6a5acc960aa909c3d6c93ff8d63649b24ee796a1
2026-02-04 13:25:47,224 - INFO - Workflow: hello_world.yml
2026-02-04 13:25:47,224 - INFO - Job: None
2026-02-04 13:25:48,229 - INFO - Using culprit finder workflow: True
2026-02-04 13:25:50,023 - INFO - Created branch culprit-finder/test-6441f5a29b8b360c957b67027bf14ba418c1879b_a6ab0861-fb65-4823-8dab-0d62b84dc3e9
2026-02-04 13:25:55,538 - INFO - Awaited for branch culprit-finder/test-6441f5a29b8b360c957b67027bf14ba418c1879b_a6ab0861-fb65-4823-8dab-0d62b84dc3e9 creation successfully
2026-02-04 13:25:55,539 - INFO - Testing commit 6441f5a29b8b360c957b67027bf14ba418c1879b on branch culprit-finder/test-6441f5a29b8b360c957b67027bf14ba418c1879b_a6ab0861-fb65-4823-8dab-0d62b84dc3e9
2026-02-04 13:25:55,539 - INFO - Triggering workflow culprit_finder.yml on culprit-finder/test-6441f5a29b8b360c957b67027bf14ba418c1879b_a6ab0861-fb65-4823-8dab-0d62b84dc3e9
2026-02-04 13:25:59,685 - INFO - No workflow runs found yet for branch culprit-finder/test-6441f5a29b8b360c957b67027bf14ba418c1879b_a6ab0861-fb65-4823-8dab-0d62b84dc3e9, waiting...
2026-02-04 13:26:29,699 - WARNING - Retrying (GithubRetry(total=9, connect=None, read=None, redirect=None, status=None)) after connection broken by 'RemoteDisconnected('Remote end closed connection without response')': /repos/google-ml-infra/jax-fork/actions/workflows/culprit_finder.yml
2026-02-04 13:26:31,753 - INFO - Deleting branch culprit-finder/test-6441f5a29b8b360c957b67027bf14ba418c1879b_a6ab0861-fb65-4823-8dab-0d62b84dc3e9
2026-02-04 13:26:32,857 - INFO - Commit 6441f5a29b8b360c957b67027bf14ba418c1879b is bad
2026-02-04 13:26:34,220 - INFO - Created branch culprit-finder/test-d263df9e78360129f14954ab350cf93d3c1d511b_112d0c8c-869f-46ed-9429-9194890e231d
2026-02-04 13:26:41,239 - INFO - Awaited for branch culprit-finder/test-d263df9e78360129f14954ab350cf93d3c1d511b_112d0c8c-869f-46ed-9429-9194890e231d creation successfully
2026-02-04 13:26:41,239 - INFO - Testing commit d263df9e78360129f14954ab350cf93d3c1d511b on branch culprit-finder/test-d263df9e78360129f14954ab350cf93d3c1d511b_112d0c8c-869f-46ed-9429-9194890e231d
2026-02-04 13:26:41,239 - INFO - Triggering workflow culprit_finder.yml on culprit-finder/test-d263df9e78360129f14954ab350cf93d3c1d511b_112d0c8c-869f-46ed-9429-9194890e231d
2026-02-04 13:26:45,678 - INFO - No workflow runs found yet for branch culprit-finder/test-d263df9e78360129f14954ab350cf93d3c1d511b_112d0c8c-869f-46ed-9429-9194890e231d, waiting...
2026-02-04 13:27:17,929 - INFO - Deleting branch culprit-finder/test-d263df9e78360129f14954ab350cf93d3c1d511b_112d0c8c-869f-46ed-9429-9194890e231d
2026-02-04 13:27:19,141 - INFO - Commit d263df9e78360129f14954ab350cf93d3c1d511b is bad

The culprit commit is: break test (SHA: d263df9e78360129f14954ab350cf93d3c1d511b)