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
poetry run carbon_guard --help
Usage: carbon_guard [OPTIONS]
โญโ 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โฆ โ
โ --nation-grid-eโฆ PARSE_URL URL for the โ
โ National Grid โ
โ ESO Carbon โ
โ Intensity API โ
โ [env var: โ
โ NATIONAL_GRID_Eโฆ โ
โ [default: โ
โ https://api.carโฆ โ
โ --co2-signal-caโฆ PARSE_URL URL for the CO2 โ
โ 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. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
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
poetry run carbon_guard --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 --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 --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.
poetry run carbon_guard --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
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.
# export CO2_SIGNAL_API_KEY=<your_api_key_here>
poetry run carbon_guard --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>
poetry run carbon_guard --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 --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 git+https://github.com/armakuni/carbon-guard.git
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
Built Distribution
Hashes for carbon_guard-0.6.0-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 872815f5dba185bf1f22f75021cdca75e9fc65e10b71b321760b9150e14ed444 |
|
| MD5 | 0b31ea86b49c0fee676b3161d7b4b448 |
|
| BLAKE2b-256 | 278ff6853223c00dad6121bbab88337fa411644bddb194ecfb8857840c62e360 |
