No project description provided
Project description
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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
carbon_guard-0.7.4.tar.gz
(58.8 kB
view details)
Built Distribution
File details
Details for the file carbon_guard-0.7.4.tar.gz.
File metadata
- Download URL: carbon_guard-0.7.4.tar.gz
- Upload date:
- Size: 58.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | c725ef88ca390e91e46a941ba4963f505dd8d813c11054a705ec48e447b4d003 |
|
| MD5 | f7ec5318b7108765d743e062c1b00dfc |
|
| BLAKE2b-256 | 2f200ab9474e1523642d092874f0ad427d55f86a80ab2f5c3fce27f44897becc |
File details
Details for the file carbon_guard-0.7.4-py3-none-any.whl.
File metadata
- Download URL: carbon_guard-0.7.4-py3-none-any.whl
- Upload date:
- Size: 12.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1dc8ae7235eecbb7c4ab3c359be9059d43104a0608773b286e4913c388485da5 |
|
| MD5 | 7f3948c37b39cbd9b7d5829d9772a3bb |
|
| BLAKE2b-256 | 312733732b36ff45488aa617ed56683dc2e92fb999b48196db7d13a37fecd0b7 |
