Feature: configurable custom OTel resource attributes for observability traces

[yskopets]

🤖 This issue has been generated by Claude Code.

Feature request

Give workflow authors a first-class way to add custom OTel resource attributes to the traces a workflow emits — beyond the fixed set gh-aw injects today (gh-aw.workflow.name, gh-aw.repository, gh-aw.run.id, github.run_id, gh-aw.engine.id).

Motivation

The observability.otlp block currently exposes only endpoint and headers. There is no supported way to attach arbitrary, workflow-defined metadata to spans as resource attributes. gh-aw composes OTEL_RESOURCE_ATTRIBUTES internally (pkg/workflow/observability_otlp.go → otelResourceAttributes) with a hard-coded list and no extension point.

Today the only workarounds are both poor:

1. Stuff metadata into OTLP headers. These are request-level HTTP headers, not span/resource attributes — they don't show up as queryable attributes on spans, and (depending on the consumer) don't reach the agent engine's own spans at all.
2. Hand-write a step that appends to OTEL_RESOURCE_ATTRIBUTES via $GITHUB_ENV. Works, but it's boilerplate every author has to reinvent, only covers the agent job, and is easy to get wrong (e.g. value encoding — see OTEL_RESOURCE_ATTRIBUTES: un-encoded workflow names (spaces) make strict OTel consumers discard the entire resource #39595).

A concrete, common driver: workflows that run in one repository but act on a different target repository (e.g. dispatched via repository_dispatch from a target repo). The target repo is not github.repository, so there's no built-in attribute for it. Authors want to tag every span with, say, the target repo so traces can be grouped/filtered by it in the tracing backend.

Proposed shape

A map of custom resource attributes under observability.otlp, values supporting GitHub Actions expressions, merged into the generated OTEL_RESOURCE_ATTRIBUTES (so they apply to gh-aw's own spans and are inherited by the engine):

observability:
  otlp:
    endpoint: ${{ secrets.OTLP_ENDPOINT }}
    resource-attributes:
      my.target-repo: ${{ github.event.client_payload.repository.full_name || github.repository }}
      my.actor: ${{ github.event.client_payload.sender.login || github.actor }}
      my.event: ${{ github.event.action || github.event_name }}

Compile-time behavior: these are appended to the existing OTEL_RESOURCE_ATTRIBUTES value gh-aw already emits, rather than overriding it.

Requirements / notes

• Values must be percent-encoded per the OTel Resource SDK spec (RFC 3986), or strict consumers discard the whole variable. This is the same correctness concern as OTEL_RESOURCE_ATTRIBUTES: un-encoded workflow names (spaces) make strict OTel consumers discard the entire resource #39595 — ideally the new field and the existing fixed attributes share one spec-correct encoder.
• Expression support is important — most useful values are ${{ github.* }} / ${{ github.event.client_payload.* }}.
• Coverage: ideally the attributes reach all jobs that emit spans (activation, agent, detection, conclusion, …), not just the agent job, so the metadata is consistent across the whole trace. (A user-authored pre-agent-steps workaround can only reach the agent job.)

Alternatives considered

• OTLP headers — wrong layer (request metadata, not span attributes); doesn't reach engine spans.
• Manual $GITHUB_ENV append in pre-agent-steps — works for the agent job only, is repetitive boilerplate, and pushes spec-encoding correctness onto every author.

Happy to help with a PR if there's interest and agreement on the schema (resource-attributes vs. a top-level observability.attributes, etc.).

[pelikhan]

@copilot parse and prevent uses of secrets. variables