## 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
```text
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