GitHub Actions "Unrecognized named-value: 'secrets'": context scoping fix

TL;DR

The secrets context is only available in certain places: jobs, steps, and specific event fields. Using secrets in a context where it is not allowed (like the top-level env, or certain if: conditions at the workflow level) produces "unrecognized named-value". The fix is moving the reference into an allowed scope, not changing the secret. The error is about where, not what.

The query

GitHub Actions "Unrecognized named-value: 'secrets'": context scoping fix

Use this when

• Workflows fail with unrecognized named-value for secrets
• Secrets referenced at the workflow top level
• Restructured workflows break secret access
• If conditions cannot see secrets

Not for when

• Secrets that exist but are empty (different issue)
• Environment-level secret scoping
• Fork PR secret restrictions

Steps

Step 1: Locate the offending reference

The error names the expression; find it in the workflow. Note its position: top-level env, jobs.[id].if, concurrency, or another restricted scope. Position is the entire diagnosis. Expected output: the reference located with its scope identified.

Step 2: Check the allowed contexts for that position

Each workflow position allows a specific set of contexts. Top-level fields allow very few; job and step fields allow secrets. Move the secret reference into a job or step where secrets is a recognized context. Expected output: the reference relocated to an allowed scope.

Step 3: Restructure instead of fighting the schema

If the logic needs the secret at a restricted level, restructure: compute the value in a job step, expose it as a job output, and reference the output where needed. Outputs flow to places secrets cannot go directly. Expected output: the workflow logic preserved with valid context usage.

Step 4: Distinguish missing secrets from scope errors

A scope error fails at parse time with "unrecognized named-value"; a missing secret produces an empty value at runtime. If your error is the former, do not go check the secret's value; fix the position. Expected output: the right problem fixed (scope, not value).

Step 5: Lint workflows for context misuse

Add workflow linting that catches context misuse at PR time. These errors are static and checkable; they should never reach the default branch. Expected output: context errors caught before merge.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_kaUjFgbJh-JObo0X5lElIg