Adding possiblity to use constant CO2 value (#132)

* Adding possiblity to use constant CO2 value

* Added grid intensity constant test

* Adapted tests to use new co2-calculation-method

* Var was not assigned after removing bracket

* Using new ECO_CI_CO2_GRID_INTENSITY_API_TOKEN

* using different constant for world

* Relaxing power values slightly

* Relaxing power values more for high load

* Typos, Indents and clarifications

Author: ArneTR

.github/workflows/constant-grid-intensity.yml

@@ -0,0 +1,95 @@
+name: Test PR & Periodic
+
+on:
+  pull_request:
+    paths-ignore:
+     - 'README.md'
+     - 'LICENSE'
+     - '.gitlab-ci.yml.example'
+     - '.gitignore'
+  schedule:
+    # only run once a week to show the action is working and preserve as much energy as possible
+    # Reason being that we pull our ML model and this could have changed in the meantime
+    - cron: '22 4 * * 6'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read
+  pull-requests: write
+
+jobs:
+  test-action:
+    runs-on: ubuntu-latest
+    continue-on-error: false
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: .
+
+      - name: Initialize Energy Estimation
+        uses: ./
+        with:
+          task: start-measurement
+          project: "Eco CI"
+          machine: "ubuntu-latest"
+          tags: "CI/CD,Test PR & Periodic-Workflow"
+          gmt-api-token: ${{ secrets.GMT_API_TOKEN }}
+
+      - name: working step
+        continue-on-error: true
+        run: |
+          timeout 2s ls -alhR / || true
+
+      - name: Final Measurement no label
+        uses: ./
+        with:
+          task: get-measurement
+
+
+      - name: Eco CI Energy Estimation
+        uses: ./
+        with:
+          task: display-results
+          pr-comment: true
+
+      - name: Validate power values
+        shell: bash
+        run: |
+          set -e
+          min=1.75
+          max=5.60
+
+          total_power=$(grep "<td>Total Run</td>" /tmp/eco-ci/output.txt | awk -F'</td><td>' '{print $4}')
+
+          awk -v p="$total_power" -v min="$min" -v max="$max" '
+          BEGIN {
+            if (p ~ /^[0-9.]+$/) {
+              printf "Total power: %.2f\n", p
+              if (p > min && p < max) {
+                exit 0
+              } else {
+                exit 1
+              }
+            } else {
+              print "Invalid power value"
+              exit 1
+            }
+          }'
+
+          status=$?
+          if [[ $status -eq 0 ]]; then
+            echo "Power value is in the expected range [$min, $max]."
+          else
+            echo "Power value is outside the expected range [$min, $max]."
+            exit 1
+          fi
+
+      - name: Validate grid intensity
+        shell: bash
+        run: |
+          if ! grep -q "472 gCO₂eq/kWh" /tmp/eco-ci/output.txt; then
+            echo "Carbon intensity 472 gCO₂eq/kWh not found in /tmp/eco-ci/output.txt"
+            exit 1
+          fi

.github/workflows/data-json-test.yml

@@ -30,7 +30,8 @@ jobs:
           machine: "ubuntu-latest"
           tags: "CI/CD,JSON-Workflow"
           gmt-api-token: ${{ secrets.GMT_API_TOKEN }}
-          electricitymaps-api-token: ${{ secrets.ELECTRICITYMAPS_TOKEN }}
+          co2-calculation-method: "location-based"
+          co2-grid-intensity-api-token: ${{ secrets.ELECTRICITYMAPS_TOKEN }}
 
       - uses: actions/setup-node@v4
         with:

.github/workflows/test.yml

@@ -51,7 +51,8 @@ jobs:
           machine: ${{ matrix.os }}
           tags: "CI/CD,Test PR & Periodic-Workflow"
           gmt-api-token: ${{ secrets.GMT_API_TOKEN }}
-          electricitymaps-api-token: ${{ secrets.ELECTRICITYMAPS_TOKEN }}
+          co2-calculation-method: "location-based"
+          co2-grid-intensity-api-token: ${{ secrets.ELECTRICITYMAPS_TOKEN }}
 
       - name: Initialize Energy Estimation (macos-14)
         if: ${{ contains(matrix.os, 'macos-14') }}
@@ -62,7 +63,8 @@ jobs:
           machine: ${{ matrix.os }}
           tags: "CI/CD,Test PR & Periodic-Workflow"
           gmt-api-token: ${{ secrets.GMT_API_TOKEN }}
-          electricitymaps-api-token: ${{ secrets.ELECTRICITYMAPS_TOKEN }}
+          co2-calculation-method: "location-based"
+          co2-grid-intensity-api-token: ${{ secrets.ELECTRICITYMAPS_TOKEN }}
           machine-power-data: "macos-14-mac-mini-m1.sh"
 
       - name: Initialize Energy Estimation (macos-13)
@@ -74,7 +76,8 @@ jobs:
           machine: ${{ matrix.os }}
           tags: "CI/CD,Test PR & Periodic-Workflow"
           gmt-api-token: ${{ secrets.GMT_API_TOKEN }}
-          electricitymaps-api-token: ${{ secrets.ELECTRICITYMAPS_TOKEN }}
+          co2-calculation-method: "location-based"
+          co2-grid-intensity-api-token: ${{ secrets.ELECTRICITYMAPS_TOKEN }}
           machine-power-data: "macos-13-mac-mini-intel.sh"
 
 

README.md

@@ -9,7 +9,7 @@ Eco CI is a project aimed at estimating energy consumption in continuous integra
 - [Usage](#usage)
   - [GitHub](#github)
     - [GitHub Action Mandatory and Optional Variables](#github-action-mandatory-and-optional-variables)
-    - [Electricity Maps Token](#electricity-maps-token)
+    - [Grid Intensity API Token](#grid-intensity-api-token)
     - [Continuing on Errors](#continuing-on-errors)
     - [Consuming the Measurements as JSON](#consuming-the-measurements-as-json)
     - [Note on Private Repos](#note-on-private-repos)
@@ -22,6 +22,7 @@ Eco CI is a project aimed at estimating energy consumption in continuous integra
     - [Trying out with Docker and Circle-CI image](#trying-out-with-docker-and-circle-ci-image)
     - [Trying out with Docker and KDE pipelines](#trying-out-with-docker-and-kde-pipelines)
   - [Jenkins](#jenkins)
+  - [Restricted Enterprise Environments](#restricted-environments)
 - [Note on the integration / Auto-Updates](#note-on-the-integration-auto-updates)
 - [Limitations / Compatibility](#limitations--compatibility)
 
@@ -123,16 +124,21 @@ jobs:
 
 - `task`: (required) (options are `start-measurement`, `get-measurement`, `display-results`)
     + `start-measurement`: Initialize the action and starts the measurement. This must be called, and only *once* per job. If called again data will be reset.
+        - `co2-calculation-method`: (optional) (default: 'constant')
+            - Can have the options `constant` or `location-based`
+            - If you use `constant` you must also set `co2-grid-intensity-constant`
+            - if you use `location-based` you must also set `co2-grid-intensity-api-token`
+        - `co2-grid-intensity-constant`: (optional) (default: 472)
+            - Constant value to be used to calculate the CO2 from the estimated energy.
+            - We use the worldwide average value from Ember compiled by The Green Web Foundation from https://github.com/thegreenwebfoundation/co2.js/blob/main/data/output/average-intensities.json#L1314 as default and update it annually.
+        - `co2-grid-intensity-api-token`: (optional)
+            - API token for the API of your choice regarding the grid intensity. See details below under [Grid Intensity API Token](#grid-intensity-api-token) which APIs are currently supported.
+            - Note that when using an API Eco CI also needs to resolve the location of the IP. Currently implemented via https://ipapi.co/
         - `branch`: (optional) (default: ${{ github.ref_name }})
           - Used to correctly identify this CI run for the Badge. Especially in PRs this will be very cryptic like `merge/72` and you might want to set this to something nicer
         - `label`: (optional) (default: 'measurement ##')
         - `send-data`: (optional) (default: true)
           - Send metrics data to metrics.green-coding.io to create and display badge, and see an overview of the energy of your CI runs. Set to false to send no data. The data we send are: the energy value and duration of measurement; cpu model; repository name/branch/workflow_id/run_id; commit_hash; source (GitHub or GitLab). We use this data to display in our green-metrics-tool front-end here: https://metrics.green-coding.io/ci-index.html
-        - `calculate-co2`: (optional) (default: true)
-          - You might typically always want this value to be shown unless you are in a restricted network and cannot make outbound requests 
-          - Gets the location using https://ipapi.co/
-          - Get the CO2 grid intensity for the location from https://www.electricitymaps.com/
-          - Estimates the amount of carbon the measurement has produced
         - `gh-api-base`: (optional) (default: 'api.github.com')
             - Eco CI uses the github api to post/edit PR comments and get the workflow id
             - set to github's default api, but can be changed if you are using github enterprise
@@ -150,8 +156,6 @@ jobs:
             - When using the GMT Dashboard and / or CarbonDB specify the endpoint URL to send to. Defaults to "https://api.green-coding.io/v2/ci/measurement/add"
         - `api-endpoint-badge-get`: (optional)
             - When using the GMT Dashboard and / or CarbonDB specify the endpoint URL to get the badge from to. Defaults to "https://api.green-coding.io//v1/ci/badge/get
-        - `electricitymaps-api-token`: (optional)
-            - API token for electricitymaps in case you get rate-limited. See details below.
 - `get-measurement`: Measures the energy at this point in time since either the start-measurement or last get-measurement action call.
     - `label`: (optional) (default: 'measurement ##')
 
@@ -167,15 +171,26 @@ jobs:
     - `json-output`: (optional) (default: false)
         - will output data to JSON to `/tmp/eco-ci/lap-data.json`
 
-#### Electricity Maps Token
+#### Grid Intensity API Token
+Used to get the grid intensity for a given location.
+We currently only support ElectricityMaps. WattTime and Entso-e are on the way! (Speed it up with a PR! ❤️)
+
+##### ElectricityMaps
+It is free for personal use but sadly it is locked to a single zone. This means that if you get it for the Zone Germany the API will fail when requesting values for the US.
+
+This is very problematic on GitHub Actions as the Us is comprised out of different zones and the machines come up in different zones. Either you buy a multi-zone key or you will have a lot of missing values.
 
-We use ElectricityMaps to get the grid intensity for a given location. 
-If you want carbon values to be displayed you must set this token. It is free for personal use. In case you need a commercial license it does not matter which zones you select, as we only use the real-time endpoint which is zone free.
 Get your key here: [https://api-portal.electricitymaps.com/](https://api-portal.electricitymaps.com/)
 
 After having obtained the token you must set it as secret and pass it in the initalization of the action (see documentation above). 
 To learn how to create a secret see the GitHub documentation: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
 
+##### WattTime
+TODO - (Speed it up with a PR! ❤️)
+
+##### Entso-e
+TODO - (Speed it up with a PR! ❤️)
+
 #### Continuing on Errors
 
 Once you have initially set up Eco CI and have given it a test spin we recommend running our action
@@ -471,6 +486,15 @@ export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH" # if macOS
   + We do **not** recommend this as it might contain beta features. We recommend using the releases and tagged versions only
 
 
+## Restricted Environments
+If you are running in restricted environments, such as an enterprise with a heavily constrained network, you can tell Eco CI to not make any outbound requests.
+
+Set:
+- `send-data` to `false`
+    - Otherwise data will be sent to the API endpoint configured in `api-endpoint-add`
+- `co2-calculation-method` to `constant`
+    - Otherwise the IP will be resolved to a location
+
 ## Limitations / Compatibility
 - At the moment this will only work with linux based pipelines, mainly tested on ubuntu images.
   + The plugin is tested on:

action.yml

@@ -25,10 +25,6 @@ inputs:
     description: 'Send metrics data to dashboard (default: metrics.green-coding.io) to create and display badge, and see an overview of the energy of your CI runs. Set to false to send no data.'
     default: true
     required: false
-  calculate-co2:
-    description: 'Uses the grid carbon intensity of the run location to estimate the emitted carbon for the measurements.'
-    default: true
-    required: false
   display-table:
     description: 'Show the energy reading results in a table during display-results step'
     default: true
@@ -81,9 +77,16 @@ inputs:
       description: 'The URL for the GMT Dashboard. Punch in yours if self-hosted. Defaults to "https://metrics.green-coding.io"'
       default: 'https://metrics.green-coding.io'
       required: false
-
-  electricitymaps-api-token:
-      description: 'API token for electricitymaps in case you get rate-limited. See documentation for details'
+  co2-calculation-method:
+    description: 'CO2 calculation can be a constant and will use a supplied fixed grid intensity. Or it can also be location based where it will use a grid intensity API provider to determine the carbon intensity value of the current machine IP.'
+    default: 'constant'
+    required: false
+  co2-grid-intensity-constant:
+    description: "Constant value to be used to calculate the CO2 from the estimated energy. We use the worldwide average value from Ember compiled by The Green Web Foundation from https://github.com/thegreenwebfoundation/co2.js/blob/main/data/output/average-intensities.json#L1314 as default and update it annually."
+    default: 472
+    required: false
+  co2-grid-intensity-api-token:
+      description: 'API token for the API of your choice regarding the grid intensity. See documentation for details'
       default: ''
       required: false
 
@@ -120,7 +123,7 @@ runs:
         workflow_id=${workflow_id:-"not_set"}
         workflow_name=${workflow_name:-"not_set"}
 
-        ${{github.action_path}}/scripts/setup.sh start_measurement "${{inputs.machine-power-data}}" "${{ github.run_id }}" "${{inputs.branch}}" "${{ github.repository }}" "$workflow_id" "$workflow_name" "${{ github.sha }}" "github" "${{ inputs.send-data }}" "${{ inputs.type }}" "${{ inputs.project }}" "${{ inputs.machine }}" "${{ inputs.tags }}" "${{ inputs.calculate-co2 }}" "${{ inputs.gmt-api-token }}" "${{ inputs.electricitymaps-api-token }}" "${{ inputs.json-output }}" "${{ inputs.api-endpoint-add }}" "${{ inputs.api-endpoint-badge-get }}" "${{ inputs.dashboard-url }}"
+        ${{github.action_path}}/scripts/setup.sh start_measurement "${{inputs.machine-power-data}}" "${{ github.run_id }}" "${{inputs.branch}}" "${{ github.repository }}" "$workflow_id" "$workflow_name" "${{ github.sha }}" "github" "${{ inputs.send-data }}" "${{ inputs.type }}" "${{ inputs.project }}" "${{ inputs.machine }}" "${{ inputs.tags }}" "${{ inputs.co2-calculation-method }}" "${{ inputs.co2-grid-intensity-constant }}" "${{ inputs.co2-grid-intensity-api-token }}" "${{ inputs.gmt-api-token }}" "${{ inputs.json-output }}" "${{ inputs.api-endpoint-add }}" "${{ inputs.api-endpoint-badge-get }}" "${{ inputs.dashboard-url }}"
 
     - if:  inputs.task == 'get-measurement'
       id: run-lap-model

eco-ci-gitlab.yml

@@ -8,14 +8,15 @@ variables:
   ECO_CI_FILTER_MACHINE: "saas-linux-small-amd64"
   ECO_CI_FILTER_TAGS: ""
   ECO_CI_JSON_OUTPUT: "false"
-  ECO_CI_CALCULATE_CO2: "true"
+  ECO_CI_CO2_CALCULATION_METHOD: "constant"
+  ECO_CI_CO2_GRID_INTENSITY_CONSTANT: 334 # for Germany in 2024 from https://app.electricitymaps.com/zone/DE/all/yearly
+  ECO_CI_CO2_GRID_INTENSITY_API_TOKEN: ""
   ECO_CI_CLONE_BRANCH: "main"
   ECO_CI_MACHINE_POWER_DATA: "gitlab_EPYC_7B12_saas-linux-small-amd64.sh"
   ECO_CI_API_ENDPOINT_ADD: "https://api.green-coding.io/v2/ci/measurement/add"
   ECO_CI_API_BADGE_GET: "https://api.green-coding.io/v1/ci/badge/get"
   ECO_CI_DASHBOARD_URL: "https://metrics.green-coding.io"
   ECO_CI_GMT_API_TOKEN: ""
-  ECO_CI_ELECTRICITYMAPS_API_TOKEN: ""
 
 .start_measurement:
     script:
@@ -26,7 +27,7 @@ variables:
             fi
             git clone --depth 1 --single-branch --branch "${ECO_CI_CLONE_BRANCH}" https://github.com/green-coding-solutions/eco-ci-energy-estimation /tmp/eco-ci-repo
 
-            /tmp/eco-ci-repo/scripts/setup.sh start_measurement "${ECO_CI_MACHINE_POWER_DATA}" "${CI_PIPELINE_ID}" "${CI_COMMIT_REF_NAME}" "${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}" "${CI_PROJECT_ID}" "gitlab-ci.yml" "${CI_COMMIT_SHA}" "gitlab" "${ECO_CI_SEND_DATA}" "${ECO_CI_FILTER_TYPE}" "${ECO_CI_FILTER_PROJECT}" "${ECO_CI_FILTER_MACHINE}" "${ECO_CI_FILTER_TAGS}" "${ECO_CI_CALCULATE_CO2}" "${ECO_CI_GMT_API_TOKEN}" "${ECO_CI_ELECTRICITYMAPS_API_TOKEN}" "${ECO_CI_JSON_OUTPUT}" "${ECO_CI_API_ENDPOINT_ADD}" "${ECO_CI_API_BADGE_GET}" "${ECO_CI_DASHBOARD_URL}"
+            /tmp/eco-ci-repo/scripts/setup.sh start_measurement "${ECO_CI_MACHINE_POWER_DATA}" "${CI_PIPELINE_ID}" "${CI_COMMIT_REF_NAME}" "${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}" "${CI_PROJECT_ID}" "gitlab-ci.yml" "${CI_COMMIT_SHA}" "gitlab" "${ECO_CI_SEND_DATA}" "${ECO_CI_FILTER_TYPE}" "${ECO_CI_FILTER_PROJECT}" "${ECO_CI_FILTER_MACHINE}" "${ECO_CI_FILTER_TAGS}" "${ECO_CI_CO2_CALCULATION_METHOD}" "${ECO_CI_CO2_GRID_INTENSITY_CONSTANT}" "${ECO_CI_CO2_GRID_INTENSITY_API_TOKEN}" "${ECO_CI_GMT_API_TOKEN}" "${ECO_CI_JSON_OUTPUT}" "${ECO_CI_API_ENDPOINT_ADD}" "${ECO_CI_API_BADGE_GET}" "${ECO_CI_DASHBOARD_URL}"
 
 .get_measurement:
     script: