[otel-advisor] OTel improvement: add github.ref and github.sha to span resource attributes

[github-actions]

📡 OTel Instrumentation Improvement: add github.ref and github.sha to span resource attributes

Analysis Date: 2026-04-05
Priority: High
Effort: Small (< 2h)

Problem

Neither github.ref (branch/tag that triggered the run) nor github.sha (commit SHA) are included as resource attributes on any span emitted by the gh-aw instrumentation. Both sendJobSetupSpan and sendJobConclusionSpan in actions/setup/js/send_otlp_span.cjs build resourceAttributes arrays (lines 406–414 for setup, lines 632–640 for conclusion) that include github.repository, github.run_id, github.event_name, and deployment.environment — but GITHUB_REF and GITHUB_SHA are never read and never emitted.

A DevOps engineer looking at traces in Grafana, Honeycomb, or Datadog today cannot answer:

• "Which branch was running when this workflow failed?"
• "Was this span from a PR branch or from main?"
• "Which commit SHA produced this error?"

Without github.ref and github.sha, correlating a failing span back to a specific commit requires manually opening the github.actions.run_url link in a separate tab — making trace-driven debugging materially slower.

Why This Matters (DevOps Perspective)

• Branch-level dashboards — Filtering spans by github.ref enables a "failures on main vs. PR branches" view in any OTel backend. This is a day-1 ask from platform teams.
• Commit-level correlation — github.sha lets engineers link a span directly to a commit in GitHub or to a deployment annotation in Grafana, reducing MTTR when a regression is introduced on a specific commit.
• deployment.environment is already set — The code already distinguishes staging vs. production via aw_info.staged. Adding github.ref alongside it enables WHERE deployment.environment = 'staging' AND github.ref = 'refs/heads/main' queries that aren't possible today.
• Low noise, high signal — Both env vars (GITHUB_REF, GITHUB_SHA) are always present in GitHub Actions runners; no conditional logic needed.

Current Behavior

// Current: actions/setup/js/send_otlp_span.cjs (lines 406–414, setup span)
const resourceAttributes = [buildAttr("github.repository", repository), buildAttr("github.run_id", runId)];
if (repository && runId) {
  const [owner, repo] = repository.split("/");
  resourceAttributes.push(buildAttr("github.actions.run_url", buildWorkflowRunUrl({ runId }, { owner, repo })));
}
if (eventName) {
  resourceAttributes.push(buildAttr("github.event_name", eventName));
}
resourceAttributes.push(buildAttr("deployment.environment", staged ? "staging" : "production"));
// ↑ github.ref and github.sha are never read or added here

The same pattern repeats at lines 632–640 for the conclusion span. GITHUB_REF and GITHUB_SHA are not read anywhere in send_otlp_span.cjs, action_setup_otlp.cjs, or action_conclusion_otlp.cjs.

Proposed Change

// Proposed addition to actions/setup/js/send_otlp_span.cjs
// In sendJobSetupSpan(), after the eventName block (around line 390):
const ref = process.env.GITHUB_REF || "";
const sha = process.env.GITHUB_SHA || "";

// Then in the resourceAttributes block (after the existing eventName push):
if (ref) {
  resourceAttributes.push(buildAttr("github.ref", ref));
}
if (sha) {
  resourceAttributes.push(buildAttr("github.sha", sha));
}

Apply the same two reads and two conditional pushes to sendJobConclusionSpan() at lines 570–640, mirroring the existing eventName pattern exactly.

Expected Outcome

After this change:

• In Grafana / Honeycomb / Datadog: spans can be grouped and filtered by github.ref (e.g., refs/heads/main vs. refs/pull/123/merge) and github.sha. Branch-level dashboards and per-commit alerting become possible without any backend schema changes.
• In the JSONL mirror (/tmp/gh-aw/otel.jsonl): the artifact already contains the full resource attributes object, so github.ref and github.sha appear automatically for post-hoc artifact inspection without any additional change.
• For on-call engineers: a failing span immediately shows the branch and commit, enabling git bisect or PR identification without leaving the trace view.

Implementation Steps

• Add const ref = process.env.GITHUB_REF || "" and const sha = process.env.GITHUB_SHA || "" in sendJobSetupSpan() (around line 390, alongside the existing eventName read)
• Push buildAttr("github.ref", ref) and buildAttr("github.sha", sha) to resourceAttributes when non-empty (in the block at lines 406–414), following the same conditional pattern as github.event_name
• Apply the same two reads and two pushes in sendJobConclusionSpan() (around lines 570 and 632–640)
• Update actions/setup/js/action_otlp.test.cjs — extend the existing "includes github.repository, github.run_id resource attributes in setup span" test (line 155) to also assert github.ref and github.sha are present when GITHUB_REF / GITHUB_SHA are set in the environment
• Add a parallel assertion in the conclusion span tests in action_otlp.test.cjs (or add a new it block) for resource attribute coverage
• Run cd actions/setup/js && npx vitest run to confirm tests pass
• Run make fmt to ensure formatting
• Open a PR referencing this issue

Evidence from Live Sentry Data

No Sentry MCP tools are configured in this workflow run, so live span payload sampling was not possible. The gap is confirmed by static analysis: grep -n "GITHUB_REF\|GITHUB_SHA" returns zero matches across send_otlp_span.cjs, action_setup_otlp.cjs, and action_conclusion_otlp.cjs. All other GitHub context variables that are present in the runner environment (GITHUB_RUN_ID, GITHUB_REPOSITORY, GITHUB_EVENT_NAME, GITHUB_ACTOR) are already captured — GITHUB_REF and GITHUB_SHA are the only two standard runner context variables missing from the resource attributes.

Related Files

• actions/setup/js/send_otlp_span.cjs — primary change (both sendJobSetupSpan and sendJobConclusionSpan)
• actions/setup/js/action_setup_otlp.cjs — no change needed (env vars consumed inside send_otlp_span.cjs)
• actions/setup/js/action_conclusion_otlp.cjs — no change needed (same reason)
• actions/setup/js/action_otlp.test.cjs — update resource-attribute assertions

---

Generated by the Daily OTel Instrumentation Advisor workflow

Generated by Daily OTel Instrumentation Advisor · ● 135.8K · ◷

• expires on Apr 12, 2026, 9:20 PM UTC