GitHub Actions "Unrecognized named-value: secrets"
An expression referenced a context that is not allowed at that position. Each workflow key permits a specific set of contexts.
What this error means
The workflow is rejected with "Unrecognized named-value: 'secrets'" (or another context) on a line where that context is not permitted.
The workflow is not valid. .github/workflows/ci.yml (Line: 5): Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.TOKENDiagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
Common causes
Context used where it is unavailable
secrets cannot be used in runs-on, job-level if at the wrong scope, or concurrency. The set of available contexts depends on the key.
Typo in the context name
Writing secret instead of secrets, or env at a spot that only allows vars, triggers the same error.
How to fix it
Move the reference to an allowed context
- Read the contexts table to see what is available for each key.
- Pass secrets through env: or with: at the step level where they are allowed.
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- run: deploy
env:
TOKEN: ${{ secrets.TOKEN }}Catch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow to prevent it
- Consult the contexts availability table before referencing a context.
- Run actionlint, which knows which contexts are valid per key.