gitgreen 0.1.1 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +73 -48
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,71 +5,96 @@ Self-contained carbon calculation CLI for GitLab jobs (no API server). It reuses
|
|
|
5
5
|
## Install
|
|
6
6
|
- From npm (global CLI):
|
|
7
7
|
```bash
|
|
8
|
-
|
|
9
|
-
# or: npm install -g gitgreen-cli
|
|
8
|
+
npm install -g gitgreen
|
|
10
9
|
gitgreen --help
|
|
11
10
|
```
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
```bash
|
|
15
|
-
# from repo root
|
|
16
|
-
pnpm -C node-module install
|
|
17
|
-
# build happens via prepare; dist/ is ready for CI
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
Run tests (pnpm preferred):
|
|
12
|
+
Run tests:
|
|
21
13
|
```bash
|
|
22
|
-
|
|
23
|
-
# or: npm --prefix node-module test
|
|
14
|
+
npm test
|
|
24
15
|
```
|
|
25
16
|
|
|
26
17
|
Stress test multiple live configs (build first, real APIs):
|
|
27
18
|
```bash
|
|
28
|
-
|
|
29
|
-
|
|
19
|
+
npm build
|
|
20
|
+
npm stress
|
|
30
21
|
```
|
|
31
22
|
|
|
32
23
|
## Usage
|
|
33
|
-
```bash
|
|
34
|
-
gitgreen \
|
|
35
|
-
--provider gcp \
|
|
36
|
-
--machine e2-standard-4 \
|
|
37
|
-
--region us-central1-a \
|
|
38
|
-
--duration 1800 \
|
|
39
|
-
--cpu 55 \
|
|
40
|
-
--budget 500 \
|
|
41
|
-
--fail-on-budget \
|
|
42
|
-
--out-md carbon-report.md \
|
|
43
|
-
--out-json carbon-report.json \
|
|
44
|
-
--post-note
|
|
45
|
-
```
|
|
46
24
|
|
|
47
|
-
###
|
|
25
|
+
### Initializing a New GitLab Project
|
|
26
|
+
|
|
27
|
+
To get started with carbon tracking in any GitLab project (any project with a remote pointing to a GitLab instance), run:
|
|
28
|
+
|
|
48
29
|
```bash
|
|
49
30
|
# In your repo
|
|
50
31
|
gitgreen init
|
|
51
32
|
```
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
33
|
+
|
|
34
|
+
The initialization wizard will guide you through the setup process:
|
|
35
|
+
- Configure provider/machine/region settings
|
|
36
|
+
- Set carbon budgets
|
|
37
|
+
- Configure MR note preferences
|
|
38
|
+
- Choose to use an existing runner or spin up a new one with supported providers
|
|
39
|
+
|
|
40
|
+
After initialization, the wizard will:
|
|
41
|
+
- Append a ready-made job to your `.gitlab-ci.yml`
|
|
42
|
+
- Print the CI/CD variable checklist (ELECTRICITY_MAPS_API_KEY, provider credentials, budget flags)
|
|
43
|
+
|
|
44
|
+
### How It Works
|
|
45
|
+
|
|
46
|
+
Once initialized, all subsequent pipelines will run on the configured runner, and their performance will be automatically measured. The carbon tracking is implemented using GitLab CI/CD components as a final step in your pipeline. The carbon tracking job itself is not computationally expensive, so it adds minimal overhead to your CI/CD workflows.
|
|
47
|
+
|
|
48
|
+
Key environment variables:
|
|
49
|
+
- `ELECTRICITY_MAPS_API_KEY` (required) - Get a free key from https://api-portal.electricitymaps.com
|
|
50
|
+
- `GCP_PROJECT_ID` / `GOOGLE_CLOUD_PROJECT` (required for GCP) - Your GCP project ID
|
|
51
|
+
|
|
52
|
+
The `gitgreen init` wizard will automatically set all necessary GitLab CI/CD variables for you.
|
|
53
|
+
|
|
54
|
+
## Providers
|
|
55
|
+
- **GCP**: Fully wired — the CLI parser expects GCP Monitoring JSON, the GitLab component polls GCE metrics, and `gitgreen init` provisions or reuses GCP runners.
|
|
56
|
+
|
|
57
|
+
## Architecture
|
|
58
|
+
Runtime flow:
|
|
71
59
|
```
|
|
72
|
-
|
|
60
|
+
CPU/RAM timeseries (GCP Monitoring JSON or custom collector)
|
|
61
|
+
|
|
|
62
|
+
v
|
|
63
|
+
+------------------+ +----------------------------+
|
|
64
|
+
| CLI (gitgreen) |--->| CarbonCalculator |
|
|
65
|
+
| - parse metrics | | - PowerProfileRepository |<- machine data in data/*.json
|
|
66
|
+
| - CLI/env opts | | - ZoneMapper (region→zone) |<- static + runtime PUE mapping
|
|
67
|
+
+------------------+ | - IntensityProvider |<- Electricity Maps API
|
|
68
|
+
+-------------+------------+
|
|
69
|
+
|
|
|
70
|
+
v
|
|
71
|
+
+-----------------------------+
|
|
72
|
+
| Report formatter |
|
|
73
|
+
| - Markdown/JSON artifacts |
|
|
74
|
+
| - Budget evaluation |
|
|
75
|
+
+-------------+---------------+
|
|
76
|
+
|
|
|
77
|
+
v
|
|
78
|
+
+-----------------------------+
|
|
79
|
+
| GitLab client (optional) |
|
|
80
|
+
| - MR note via CI_JOB_TOKEN |
|
|
81
|
+
+-----------------------------+
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
GitLab CI path:
|
|
85
|
+
```
|
|
86
|
+
Pipeline starts → component script fetches CPU/RAM timeseries from GCP Monitoring
|
|
87
|
+
→ writes JSON files → runs `gitgreen --provider gcp ...`
|
|
88
|
+
→ emits `carbon-report.md` / `carbon-report.json`
|
|
89
|
+
→ optional MR note when CI_JOB_TOKEN is present
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Adding a provider
|
|
93
|
+
1. Extend `CloudProvider` and the provider guard in `src/index.ts` so the calculator accepts the new key.
|
|
94
|
+
2. Add machine power data (`<provider>_machine_power_profiles.json`) and, if needed, CPU profiles to `data/`, then update `PowerProfileRepository.loadMachineData` to load it.
|
|
95
|
+
3. Map regions to Electricity Maps zones and a PUE default in `ZoneMapper` (or via `data/runtime-pue-mappings.json` for runtime overrides).
|
|
96
|
+
4. Parse that provider's metrics into the `TimeseriesPoint` shape (timestamp + numeric value) alongside RAM size/usage, and update the CLI/init/templates to pull those metrics.
|
|
97
|
+
5. Wire any CI automation (runner tags, MR note flags) to pass the correct provider, machine type, and region strings.
|
|
73
98
|
|
|
74
99
|
## Publish
|
|
75
100
|
- Ensure version bump in `package.json`
|