Carbon Guard 👮
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.
Usage
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. │
╰──────────────────────────────────────────────────────────────────────────────╯
Check
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. │
╰──────────────────────────────────────────────────────────────────────────────╯
Schedule
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. │
╰──────────────────────────────────────────────────────────────────────────────╯
Common use case
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=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
uv 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
uv 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
Data Sources
You may change the data source by specifying the --data-source flag.
National Grid ESO Carbon Intensity
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=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.
uv run carbon_guard schedule --data-source national-grid-eso-carbon-intensity --within "1 hour"
2023-07-07T09:30:00+00:00
CO2 Signal
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=GB
Carbon intensity is 107 gCO2eq/kWh, which is below or equal to the max of 100000 gCO2eq/kWh
Errors
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=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=""
uv 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.
Adding to your pipelines
This tool is intended to be run inside a pipeline to either fail or skip steps within, based on the current carbon intensity levels.
Using GitHub Actions
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 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/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'
Other pipelines
You can run in other pipelines as a command line tool
pip install carbon-guard
carbon_guard --help
1 maintainer
Release files for carbon-guard 0.7.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| carbon_guard-0.7.4.tar.gz | 58.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| carbon_guard-0.7.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size:71.3 kB
Release files / carbon_guard-0.7.4.tar.gz
| Download URL | carbon_guard-0.7.4.tar.gz |
|---|---|
| Size | 58.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c725ef88ca390e91e46a941ba4963f505dd8d813c11054a705ec48e447b4d003
|
|
BLAKE2b-256 checksum How to use checksums |
2f200ab9474e1523642d092874f0ad427d55f86a80ab2f5c3fce27f44897becc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.1.1 CPython/3.12.7
|
Release files / carbon_guard-0.7.4-py3-none-any.whl
| Download URL | carbon_guard-0.7.4-py3-none-any.whl |
|---|---|
| Size | 12.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1dc8ae7235eecbb7c4ab3c359be9059d43104a0608773b286e4913c388485da5
|
|
BLAKE2b-256 checksum How to use checksums |
312733732b36ff45488aa617ed56683dc2e92fb999b48196db7d13a37fecd0b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.1.1 CPython/3.12.7
|
