Carbon Guard is a unique and environmentally conscious GitHub Action & CLI App designed to help reduce the carbon footprint of your CI/CD pipelines. It works by monitoring real-time carbon intensity data and preventing pipelines from running when the carbon intensity is high.
uv run carbon_guard --help
Usage: carbon_guard [OPTIONS] COMMAND [ARGS]...
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy │
│ it or customize the installation. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ check Check the current carbon intensity. │
│ schedule Find the lowest carbon time. │
╰──────────────────────────────────────────────────────────────────────────────╯
uv run carbon_guard check --help
Usage: carbon_guard check [OPTIONS]
Check the current carbon intensity.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --max-carbon-in… INTEGER Set the max │
│ carbon intensity │
│ in gCO2eq/kWh. │
│ [env var: │
│ MAX_CARBON_INTE… │
│ [default: None] │
│ [required] │
│ --advise-only --no-advise-on… Do not exit with │
│ an error if the │
│ carbon intensity │
│ is above the max │
│ carbon │
│ intensity. │
│ [env var: │
│ ADVISE_ONLY] │
│ [default: │
│ no-advise-only] │
│ --data-source [file|national-g Where to read │
│ rid-eso-carbon-i carbon intensity │
│ ntensity|co2-sig data from │
│ nal] [env var: │
│ DATA_SOURCE] │
│ [default: │
│ national-grid-e… │
│ --from-file-car… PATH File to read │
│ carbon intensity │
│ from in file │
│ mode │
│ [env var: │
│ FROM_FILE_CARBO… │
│ [default: │
│ .carbon_intensi… │
│ --national-grid… HTTP_OR_HTTPS_UR URL for the │
│ L National Grid │
│ ESO Carbon │
│ Intensity API │
│ [env var: │
│ NATIONAL_GRID_E… │
│ [default: │
│ https://api.car… │
│ --co2-signal-ca… HTTP_OR_HTTPS_UR URL for the CO2 │
│ L Signal api │
│ [env var: │
│ CO2_SIGNAL_API_… │
│ [default: │
│ https://api.co2… │
│ --co2-signal-ap… TEXT Api key for the │
│ CO2 Signal api, │
│ required in CO2 │
│ Signal mode │
│ [env var: │
│ CO2_SIGNAL_API_… │
│ [default: None] │
│ --co2-signal-co… TEXT Country code to │
│ get the carbon │
│ intensity from │
│ CO2 Signal api │
│ [env var: │
│ CO2_SIGNAL_COUN… │
│ [default: None] │
│ --help Show this │
│ message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
uv run carbon_guard schedule --help
Usage: carbon_guard schedule [OPTIONS]
Find the lowest carbon time.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --within HUMAN_READABLE_DURATI Time period to │
│ ON predict the lowest │
│ intensity within │
│ [env var: WITHIN] │
│ [default: None] │
│ [required] │
│ --data-source [file|national-grid-e Where to read carbon │
│ so-carbon-intensity] intensity data from │
│ [env var: │
│ DATA_SOURCE] │
│ [default: │
│ national-grid-eso-ca… │
│ --from-file-carbon-i… PATH File to read carbon │
│ intensity from in │
│ file mode │
│ [env var: │
│ FROM_FILE_CARBON_INT… │
│ [default: │
│ .carbon_intensity] │
│ --national-grid-eso-… HTTP_OR_HTTPS_URL URL for the National │
│ Grid ESO Carbon │
│ Intensity API │
│ [env var: │
│ NATIONAL_GRID_ESO_CA… │
│ [default: │
│ https://api.carbonin… │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
When comparing current carbon intensity levels to global carbon intensity based on gCO2eq/kWh.
Comparing carbon levels with the expected outcome for high carbon intensity:
carbon_intensity_is 1000
uv run carbon_guard check --max-carbon-intensity=999Carbon intensity is 1000 gCO2eq/kWh, which is above the max of 999 gCO2eq/kWh
You may also return a successful exit code even on high carbon intensity by passing the --advise-only flag.
carbon_intensity_is 1000
uv run carbon_guard check --max-carbon-intensity=999 --advise-onlyComparing carbon levels with the expected outcome for low carbon intensity:
carbon_intensity_is 999
uv run carbon_guard check --max-carbon-intensity=999Carbon intensity is 999 gCO2eq/kWh, which is below or equal to the max of 999 gCO2eq/kWh
You may change the data source by specifying the --data-source flag.
Using the national-grid-eso-carbon-intensity data source. [note] this only supplies data for the United Kingdom.
uv run carbon_guard check --data-source national-grid-eso-carbon-intensity --max-carbon-intensity=100000Carbon intensity is 98 gCO2eq/kWh, which is below or equal to the max of 100000 gCO2eq/kWh
You can use this data provider to schedule find the forecasted lowest carbon intensity within a given time period.
uv run carbon_guard schedule --data-source national-grid-eso-carbon-intensity --within "1 hour"2023-07-07T09:30:00+00:00
Using the co2-signal data source [note] This data source requires an account (free/paid) which will supply an API key for usage, and does not support forecasting.
# export CO2_SIGNAL_API_KEY=<your_api_key_here>
uv run carbon_guard check --data-source co2-signal --max-carbon-intensity=100000 --co2-signal-country-code=GBCarbon intensity is 107 gCO2eq/kWh, which is below or equal to the max of 100000 gCO2eq/kWh
if you don't provide a co2-signal-country-code the call will fail.
# export CO2_SIGNAL_API_KEY=<your_api_key_here>
uv run carbon_guard check --data-source co2-signal --max-carbon-intensity=100000No country code provided to CO2 Signal Api.
if you don't provide a co2-signal-api-key the call will fail.
export CO2_SIGNAL_API_KEY=""
uv run carbon_guard check --data-source co2-signal --max-carbon-intensity=100000 --co2-signal-country-code=GBNo API key found for CO2 Signal API.
This tool is intended to be run inside a pipeline to either fail or skip steps within, based on the current carbon intensity levels.
If you intend to fail the build based on the carbon intensity level
validate-action:
runs-on: ubuntu-latest
steps:
- uses: armakuni/carbon-guard@v0.4.1
with:
max_carbon_intensity: 500
- run: echo Some complicated compute taskAlternatively if you want to simply skip a step if the carbon intensity is too high you can use the continue-on-error
flag.
validate-action:
runs-on: ubuntu-latest
steps:
- uses: armakuni/carbon-guard@v0.4.1
continue-on-error: true
id: carbon_guard
with:
max_carbon_intensity: 500
- run: echo Some complicated compute task
if: steps.carbon_guard.outcome == 'success'You can run in other pipelines as a command line tool
pip install carbon-guard
carbon_guard --help