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.
poetry 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. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
poetry 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. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
poetry 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
poetry run carbon_guard check --max-carbon-intensity=999
Carbon 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
poetry run carbon_guard check --max-carbon-intensity=999 --advise-only
Comparing carbon levels with the expected outcome for low carbon intensity:
carbon_intensity_is 999
poetry run carbon_guard check --max-carbon-intensity=999
Carbon 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.
poetry run carbon_guard check --data-source national-grid-eso-carbon-intensity --max-carbon-intensity=100000
Carbon 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.
poetry 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>
poetry run carbon_guard check --data-source co2-signal --max-carbon-intensity=100000 --co2-signal-country-code=GB
Carbon 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>
poetry run carbon_guard check --data-source co2-signal --max-carbon-intensity=100000
No 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=""
poetry run carbon_guard check --data-source co2-signal --max-carbon-intensity=100000 --co2-signal-country-code=GB
No 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/[email protected]
with:
max_carbon_intensity: 500
- run: echo Some complicated compute task
Alternatively 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/[email protected]
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