Package: carbon-guard
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.Usagepoetry run carbon_guard --helpUsage: 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.                                │
╰──────────────────────────────────────────────────────────────────────────────╯Checkpoetry run carbon_guard check --helpUsage: 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.            │
╰──────────────────────────────────────────────────────────────────────────────╯Schedulepoetry run carbon_guard schedule --helpUsage: 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 caseWhen 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=999Carbon intensity is 1000 gCO2eq/kWh, which is above the max of 999 gCO2eq/kWhYou may also return a successful exit code even on high carbon intensity by passing the--advise-onlyflag.carbon_intensity_is 1000
poetry run carbon_guard check --max-carbon-intensity=999 --advise-onlyComparing carbon levels with the expected outcome for low carbon intensity:carbon_intensity_is 999
poetry run carbon_guard check --max-carbon-intensity=999Carbon intensity is 999 gCO2eq/kWh, which is below or equal to the max of 999 gCO2eq/kWhData SourcesNational Grid ESO Carbon IntensityCO2 SignalYou may change the data source by specifying the--data-sourceflag.National Grid ESO Carbon IntensityUsing thenational-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=100000Carbon intensity is 98 gCO2eq/kWh, which is below or equal to the max of 100000 gCO2eq/kWhYou 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:00CO2 SignalUsing theco2-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=GBCarbon intensity is 107 gCO2eq/kWh, which is below or equal to the max of 100000 gCO2eq/kWhErrorsif you don't provide aco2-signal-country-codethe call will fail.# export CO2_SIGNAL_API_KEY=<your_api_key_here>
poetry run carbon_guard check --data-source co2-signal --max-carbon-intensity=100000No country code provided to CO2 Signal Api.if you don't provide aco2-signal-api-keythe 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=GBNo API key found for CO2 Signal API.Adding to your pipelinesThis 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 ActionsIf you intend to fail the build based on the carbon intensity levelvalidate-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 thecontinue-on-errorflag.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 pipelinesYou can run in other pipelines as a command line toolpip install carbon-guard
carbon_guard --help