Actions "Unrecognized named-value: 'secrets'" in CI

The secrets context is only available in certain places. Using secrets.X where it is not allowed, such as a job-level if, a service container key, or a workflow_call input default, produces "Unrecognized named-value: 'secrets'" at parse time.

What this error means

The workflow fails to start (a validation/parse error) with "Unrecognized named-value: 'secrets'", pointing at an expression that references the secrets context outside its allowed scope.

The workflow is not valid. .github/workflows/ci.yml: Unrecognized
named-value: 'secrets'. Located at position 1 within expression:
secrets.DEPLOY_KEY != ''

Common causes

secrets used where the context is unavailable

Contexts like secrets are not valid in a job-level if, some container/service fields, or input defaults, so the parser rejects the reference.

A secrets reference in a reusable workflow input

Defining a workflow_call input default from secrets is not allowed; secrets are passed separately.

How to fix it

Move the secret reference into a step

1. Reference secrets.X inside a step (env or run), where the context is available.
2. For a conditional, compute a boolean in a step output and gate on that.
3. Re-validate the workflow.

steps:
  - id: check
    run: echo "has=${{ secrets.DEPLOY_KEY != '' }}" >> "$GITHUB_OUTPUT"
  - if: steps.check.outputs.has == 'true'
    run: ./deploy.sh

Pass secrets through the proper channel

For reusable workflows, pass secrets via the secrets: mapping rather than embedding them in input defaults.

jobs:
  call:
    uses: ./.github/workflows/deploy.yml
    secrets: inherit

How to prevent it

• Use the secrets context only where it is allowed (steps, env).
• Compute conditionals from step outputs, not from secrets in a job if.
• Pass secrets to reusable workflows via the secrets: mapping.

Related guides