BUILD-11295 Gate cache-metrics on layered decision file (workflow env > pre-job file)

[julien-carsique-sonarsource]

Summary

Replaces the simple env.CI_METRICS_ENABLED == 'true' gate on the cache-metrics-prep step with a layered check that honours both the workflow-level env override AND a presence-only decision file ${CI_METRICS_DIR}/enabled written by the runner pre-job hook (in github-runners-infra, see Validation chain below).

Resolution (a new early step Resolve CI metrics gate does this in bash, then exposes the result as steps.ci-metrics-gate.outputs.decision):

• workflow env.CI_METRICS_ENABLED == 'false' → off (beats everything) — also rm -f the decision file so the post-job hook agrees
• workflow env.CI_METRICS_ENABLED == 'true' → on (beats the allow/deny lists) — also touch the decision file
• otherwise on iff ${CI_METRICS_DIR}/enabled exists at job-start

New gate (one expression on Prepare local cache-metrics sub-action):

if: >-
  steps.ci-metrics-gate.outputs.decision == 'true' &&
  steps.cache-backend.outputs.cache-backend == 's3'

We resolve in bash rather than splitting workflow-env vs. file-presence between a case step and a GHA if: expression because GHA's hashFiles() only accepts paths under $GITHUB_WORKSPACE — it returns empty for /tmp/ci-metrics/enabled. Resolving in shell and emitting a step output keeps the gate one-shot and correct on every path.

Validation chain

• end-to-end validator (TEST, DO NOT MERGE): https://github.com/SonarSource/sonar-dummy/pull/592
  • transitive pin (TEST, DO NOT MERGE): BUILD-11295 test gh-action_cache@feat/.../BUILD-11295-metricsFeatureFlag ci-github-actions#267
  • cache-action gate: BUILD-11295 Gate cache-metrics on layered decision file (workflow env > pre-job file) #71 — this PR
  • runner pre-job hook (deployed with deploy-dev label): https://github.com/SonarSource/github-runners-infra/pull/410

Test plan

• YAML lint + actionlint pass.
• test-cache-metrics-via-decision-file (new) — file-only path, no env override. Pre-touches ${CI_METRICS_DIR}/enabled, verifies cache-metrics emit fires.
• test-cache-metrics-workflow-false-beats-file (new) — env=false beats pre-touched file; verifies the propagator rm -f'd the file and metrics did NOT emit.
• Existing env=true tests (test-cache-metrics-output, test-s3-cache-survives-git-clean-with-metrics) — still pass under the new gate.
• All 26 CI checks green.
• End-to-end validation through SonarSource/sonar-dummy#592 → BUILD-11295 test gh-action_cache@feat/.../BUILD-11295-metricsFeatureFlag ci-github-actions#267 → this PR, on sonar-dev runners — all checks green.

Links

• Jira: https://sonarsource.atlassian.net/browse/BUILD-11295
• Design comment: https://sonarsource.atlassian.net/browse/BUILD-11295?focusedCommentId=919695

[sonar-review-alpha]

Summary

This PR replaces a simple CI_METRICS_ENABLED == 'true' gate with a layered decision system that respects both workflow-level environment overrides and a runner-side signal file.

What changed:

• New Resolve CI metrics gate step in action.yml (bash) that evaluates three paths in priority order:
  1. CI_METRICS_ENABLED='true' → metrics on (and touch decision file for post-job hook)
  2. CI_METRICS_ENABLED='false' → metrics off (and remove decision file)
  3. Otherwise → metrics on iff ${CI_METRICS_DIR}/enabled exists (written by runner pre-job hook)
• The gate step outputs decision (true/false), replacing the inline env check in the Prepare local cache-metrics sub-action conditional
• Two new test jobs covering the file-only path and the workflow-env-override-beats-file path
• README documentation of the three-tier resolution strategy for operators and workflow authors

Why: Enables metrics gatekeeping via both workflow-level overrides (for explicit opt-in/out) and per-runner allow/deny lists (configured in github-runners-infra), while keeping the gate decision testable and the post-job hook synchronized.

What reviewers should know

Key files to review:

1. action.yml (lines 247–283): The new Resolve CI metrics gate step is the heart of the change. It's straightforward bash with clear case logic—read this first to understand the three paths.

2. README.md (lines 192–209): "Gate resolution" section documents the priority order and use cases. This is reference material for understanding why the step does what it does.

3. test-action.yml (two new jobs):

   • test-cache-metrics-via-decision-file: Exercises the file-only path (step outputs should be set, JSON written).
   • test-cache-metrics-workflow-false-beats-file: Exercises workflow opt-out, verifies the file is cleaned up and metrics did not emit.

Non-obvious details:

• The step mutates ${CI_METRICS_DIR}/enabled (touch on true, rm on false) so the post-job hook in github-runners-infra sees the same decision. This is important for audit trails.
• The step only runs on Linux (if: runner.os == 'Linux'), matching the existing restriction on metrics collection.
• The gate conditional changed from env.CI_METRICS_ENABLED == 'true' to steps.ci-metrics-gate.outputs.decision == 'true'—no additional S3/backend checks were added (those remain).

Testing notes: Existing tests for CI_METRICS_ENABLED=true should still pass (the author confirms this). The two new tests specifically validate the new decision paths.

---

• Generate Walkthrough
• Generate Diagram

🗣️ Give feedback

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues
0 New dependency risks

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonarqube-cloud-us]

Quality Gate passed

Issues
0 New issues
0 Accepted issues
0 New dependency risks

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonar-review-alpha]

LGTM! ✅

Solid implementation. The gate logic, file mutation side-effect, and non-Linux safety are all correct. Nothing here requires changes before merge.

A few things worth understanding as you read:

• Non-Linux safety: The runner.os == 'Linux' guard that was previously on Prepare local cache-metrics sub-action is now implicit — since ci-metrics-gate only runs on Linux, its output is empty on other OSes, and '' == 'true' is false. The behaviour is identical; it's just expressed differently.
• File mutation is intentional: When CI_METRICS_ENABLED is set to true or false, the gate step touches/removes ${CI_METRICS_DIR}/enabled so the post-job job-completed.sh hook sees the same decision. This couples the action to the hook via a shared file, which is documented in the README.
• Test path convention: Verify steps hardcode /tmp/ci-metrics rather than expanding ${CI_METRICS_DIR:-/tmp/ci-metrics} — consistent with the pre-existing test-cache-metrics-output job (line 411). These tests assume CI_METRICS_DIR is unset or equals /tmp/ci-metrics on github-ubuntu-latest-s, which holds given all 26 checks are green.

🗣️ Give feedback