doc/ci/sustainability/eco_ci.md
{{< details >}}
{{< /details >}}
[!note] Eco CI is a third-party tool that integrates with GitLab CI/CD pipelines. GitLab does not maintain or provide support for this tool, and makes no representation that this tool satisfies any regulatory or compliance requirements.
Eco CI is an open source tool that measures the energy consumption and carbon emissions of CI/CD pipelines.
Add Eco CI to your pipeline to measure energy consumption and carbon emissions during job execution.
Eco CI uses the ECO_CI_LABEL variable to identify and group your measurements,
so choose a descriptive name that represents your project or pipeline stage.
By default, measurement data is sent to the Green Coding Solutions dashboard for
analysis, but you can set ECO_CI_SEND_DATA to false to store results locally only.
Prerequisites:
curl, jq, awk, bash, git, and coreutils utilities.To add Eco CI to your pipeline:
In your .gitlab-ci.yml file, include the Eco CI template and configure your project identifier:
variables:
ECO_CI_LABEL: "my-project-pipeline"
ECO_CI_SEND_DATA: "false"
include:
- remote: 'https://raw.githubusercontent.com/green-coding-solutions/eco-ci-energy-estimation/main/eco-ci-gitlab.yml'
Add measurement scripts to your jobs:
build-job:
image: node:alpine
before_script:
- apk add --no-cache curl jq gawk bash git coreutils
script:
- !reference [.start_measurement, script]
- npm install
- npm run build
- npm test
- !reference [.get_measurement, script]
- !reference [.display_results, script]
artifacts:
paths:
- eco-ci-output.txt
- metrics.txt
expire_in: 1 week
Optional. To measure commands separately, use measurement scripts for each command:
build-job:
image: node:alpine
before_script:
- apk add --no-cache curl jq gawk bash git coreutils
script:
- !reference [.start_measurement, script]
- npm install
- !reference [.get_measurement, script]
- !reference [.display_results, script]
- !reference [.start_measurement, script]
- npm run build
- !reference [.get_measurement, script]
- !reference [.display_results, script]
- !reference [.start_measurement, script]
- npm test
- !reference [.get_measurement, script]
- !reference [.display_results, script]
artifacts:
paths:
- eco-ci-output.txt
- metrics.txt
expire_in: 1 week
Eco CI stores measurement results in job artifacts that you can access through the GitLab interface. The measurement results include:
To view measurement results:
eco-ci-output.txt file.Example output:
"build-job: Label: my-project-pipeline: Energy Used [Joules]:" 5.82
"build-job: Label: my-project-pipeline: Avg. CPU Utilization:" 22.69
"build-job: Label: my-project-pipeline: Avg. Power [Watts]:" 1.91
"build-job: Label: my-project-pipeline: Duration [seconds]:" 3.04
----------------
"build-job: Energy [Joules]:" 5.82
"build-job: Avg. CPU Utilization:" 22.69
"build-job: Avg. Power [Watts]:" 1.91
"build-job: Duration [seconds]:" 3.04
----------------
🌳 CO2 Data:
CO₂ from energy is: 0.001944 g
CO₂ from manufacturing (embodied carbon) is: 0.000442 g
Carbon Intensity for this location: 334 gCO₂eq/kWh
SCI: 0.002386 gCO₂eq / pipeline run emitted
If you set ECO_CI_SEND_DATA to true, measurement data is automatically sent to
the Eco CI metrics dashboard.
The dashboard provides historical records, trend analysis, and comparison between pipeline runs.
By default, the dashboards are public and can be viewed by anyone.
You can view energy consumption trends over time, carbon emission patterns,
and compare measurements across different branches, commits, or time periods.
Access the dashboard with your project's ECO_CI_LABEL identifier.
You can display an Eco CI badge in your project's README.md file to show energy consumption metrics.
Prerequisites:
ECO_CI_SEND_DATA must be set to true.To add the badge to the README.md file:
Copy and paste the following into your README.md file:
[](https://metrics.green-coding.io/ci.html?repo=<namespace>/<project>&branch=<branch>&workflow=<project-id>)
Replace the placeholders:
<namespace>/<project> with your GitLab project path (for example, mygroup/myproject)<branch> with your branch name (for example, main)<project-id> with your GitLab project ID (for example, 52215136)Example:
[](https://metrics.green-coding.io/ci.html?repo=lyspin/eco-ci-demo&branch=main&workflow=52215136)
When you work with Eco CI, you might encounter the following issues.
You might get an error message:
ERROR: Date has returned a timestamp that is not accurate to microseconds! You may need to install `coreutils`.
This issue occurs when using Alpine Linux or other minimal distributions that don't include GNU coreutils by default.
To resolve this issue, install coreutils. For example, with Alpine:
before_script:
- apk add --no-cache coreutils
You don't see the eco-ci-output.txt file in your job artifacts.
This issue occurs when the job is missing the artifacts configuration.
To resolve this issue, ensure your job contains the correct artifacts configuration:
artifacts:
paths:
- eco-ci-output.txt
- metrics.txt
Your eco-ci-output.txt file shows values like Energy [Joules]: 0.00.
This issue occurs when measurement scripts are placed incorrectly.
To resolve this issue, ensure measurement scripts surround CPU-intensive commands:
script:
- !reference [.start_measurement, script]
- npm install # CPU-intensive command
- npm run build # CPU-intensive command
- !reference [.get_measurement, script]
- !reference [.display_results, script]