release: 1.9.3

Author: peterklingelhofer

check_grid.py

@@ -67,6 +67,7 @@
     DEFAULT_JOB_DURATION_HOURS,
     DEFAULT_TIMEOUT,
     GLOBAL_AVG_INTENSITY,
+    ci_secret_hint,
     last_failure_reason,
 )
 from providers.runners import (
@@ -340,15 +341,17 @@ def _emit_token_warnings(zones_config, emaps_api_key, entsoe_token):
         extra = f" (+{len(needs_emaps) - 5} more)" if len(needs_emaps) > 5 else ""
         print(
             f"::notice::Zones [{zones_str}{extra}] need electricity_maps_token. "
-            f"Get free at https://portal.electricitymaps.com/"
+            f"Get free at https://portal.electricitymaps.com/ "
+            f"and {ci_secret_hint('electricity_maps_token')}."
         )
 
     if needs_entsoe:
         zones_str = ", ".join(needs_entsoe[:5])
         extra = f" (+{len(needs_entsoe) - 5} more)" if len(needs_entsoe) > 5 else ""
         print(
             f"::notice::Zones [{zones_str}{extra}] would use ENTSO-E with entsoe_token. "
-            f"Get free at https://transparency.entsoe.eu/"
+            f"Get free at https://transparency.entsoe.eu/ "
+            f"and {ci_secret_hint('entsoe_token')}."
         )
 
 

providers/base.py

@@ -544,3 +544,22 @@ def iso_now() -> str:
 def github_headers(token: str) -> dict:
     """Standard bearer auth + accept headers for the GitHub REST API."""
     return {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"}
+
+
+_CI_SECRET_INSTRUCTIONS = {
+    "GITHUB_ACTIONS": "Settings -> Secrets and variables -> Actions",
+    "GITLAB_CI": "Settings -> CI/CD -> Variables",
+    "CIRCLECI": "Project Settings -> Environment Variables",
+    "BITBUCKET_BUILD_NUMBER": "Repository settings -> Pipelines -> Repository variables",
+    "TF_BUILD": "Pipeline -> Edit -> Variables",
+    "TRAVIS": "Repository Settings -> Environment Variables",
+    "JENKINS_URL": "Manage Jenkins -> Credentials (or pipeline environment block)",
+}
+
+
+def ci_secret_hint(secret_name: str) -> str:
+    """Return a platform-specific hint for where to add a CI secret."""
+    for env_var, location in _CI_SECRET_INSTRUCTIONS.items():
+        if os.environ.get(env_var):
+            return f"add it as a secret named {secret_name} ({location})"
+    return f"set {secret_name} as a secret or environment variable in your CI/CD platform"

providers/eia.py

@@ -7,6 +7,7 @@
     EIA_EMISSION_FACTORS,
     EIA_STORAGE_FUELS,
     api_request,
+    ci_secret_hint,
     compute_trend,
     green_result,
 )
@@ -108,7 +109,8 @@ def check_carbon_intensity(zone, max_carbon, eia_api_key=""):
     if api_key == "DEMO_KEY":
         print(
             "::notice::Using built-in EIA DEMO_KEY (rate limit ~30 req/hr). "
-            "For higher limits, register a free key at https://www.eia.gov/opendata/register.php"
+            "For higher limits, register a free key at https://www.eia.gov/opendata/register.php "
+            f"and {ci_secret_hint('EIA_API_KEY')}."
         )
     url = (
         f"{EIA_API_BASE}/electricity/rto/fuel-type-data/data"

providers/electricity_maps.py

@@ -12,7 +12,7 @@
 sold per country/year, not a cheap flat key.
 """
 
-from providers.base import api_request_with_header, compute_trend, green_result
+from providers.base import api_request_with_header, ci_secret_hint, compute_trend, green_result
 
 EMAPS_API_BASE = "https://api-access.electricitymaps.com/free-tier"
 
@@ -25,8 +25,8 @@ def check_carbon_intensity(zone, max_carbon, emaps_api_key):
     if not emaps_api_key:
         print(
             f"::error::Electricity Maps API token required for zone '{zone}'. "
-            "Get a free token in 30 seconds at https://portal.electricitymaps.com/ "
-            "and set the electricity_maps_token input."
+            "Get a free token at https://portal.electricitymaps.com/ "
+            f"and {ci_secret_hint('electricity_maps_token')}."
         )
         return None, None
 

providers/entsoe.py

@@ -10,7 +10,7 @@
 import xml.etree.ElementTree as ET
 from datetime import datetime, timedelta, timezone
 
-from providers.base import DEFAULT_FUEL_FACTOR, FUEL_FACTORS, green_result, request
+from providers.base import DEFAULT_FUEL_FACTOR, FUEL_FACTORS, ci_secret_hint, green_result, request
 
 ENTSOE_API_BASE = "https://web-api.tp.entsoe.eu/api"
 
@@ -269,10 +269,13 @@ def check_carbon_intensity(zone, max_carbon, entsoe_token):
     Returns (is_green, intensity) or (None, None) on error.
     """
     if not entsoe_token:
+        reg_url = (
+            "https://transparency.entsoe.eu/ (Login -> Account Settings -> Web API Security Token)"
+        )
         print(
             f"::error::ENTSO-E security token required for zone '{zone}'. "
-            "Register free at https://transparency.entsoe.eu/ → Login → "
-            "Account Settings → Web API Security Token."
+            f"Register free at {reg_url} "
+            f"and {ci_secret_hint('entsoe_token')}."
         )
         return None, None
 
@@ -304,10 +307,13 @@ def check_carbon_intensity(zone, max_carbon, entsoe_token):
         return None, None
 
     if response.status_code == 401:
+        reg_url = (
+            "https://transparency.entsoe.eu/ (Login -> Account Settings -> Web API Security Token)"
+        )
         print(
-            "::error::ENTSO-E authentication failed. Check your entsoe_token secret. "
-            "Get a free token at https://transparency.entsoe.eu/ → Account Settings → "
-            "Web API Security Token."
+            "::error::ENTSO-E authentication failed. "
+            f"{ci_secret_hint('entsoe_token').capitalize()}. "
+            f"Get a free token at {reg_url}."
         )
         return None, None
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "carbon-aware-dispatcher"
-version = "1.9.2"
+version = "1.9.3"
 description = "Run CI/CD only when the energy grid is clean. Free, zero-config carbon-aware scheduling for US, UK and more"
 readme = "README.md"
 license = "MIT"