mediumIntermediateSymptom-first#workflow_dispatch#inputs#secrets#manual-trigger

workflow_dispatch inputs not passed - secrets vs inputs mismatch

Manually triggered workflow fails because input is empty

Likely source:configurationdeployment

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Manually triggered workflow fails because input is empty
  • Steps that reference github.event.inputs.<name> get empty string
  • Workflow expects secrets but inputs were used instead

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Workflow input definitions

    cat .github/workflows/<file>.yml | grep -A20 'workflow_dispatch:'

  • Actual inputs passed in the run

    gh api repos/<OWNER/REPO>/actions/runs/<RUN_ID> --jq '.inputs'

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • gh workflow run was called without -f key=value flags
  • Inputs object in the run is empty

Confirm before fixing

gh api repos/<OWNER/REPO>/actions/runs/<RUN_ID> --jq '.inputs'
READ

Check the inputs sent with the run

Fix

gh workflow run <file>.yml -f environment=production -f version=<TAG>
CHANGE

Re-trigger with the required inputs

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
cat .github/workflows/<file>.yml | grep -A20 'workflow_dispatch:'
READ

Read the input definitions

2
gh api repos/<OWNER/REPO>/actions/runs/<RUN_ID> --jq '.inputs'
READ

Check what was passed

3
grep -n 'secrets\|inputs' .github/workflows/<file>.yml
READ

Find secrets vs inputs references

4
gh workflow run <file>.yml -f <KEY>=<VALUE>
CHANGE

Re-trigger with correct inputs

Prevention

  • Always set required: true on mandatory inputs and provide sensible defaults for optional ones.
  • Document the expected inputs in a comment block above the workflow_dispatch trigger.
  • Test manual triggers in a development workflow before using them in production.
  • Use 'inputs' not 'secrets' for values that the user provides at trigger time.

Related runbooks

Same stack, same failure family — worth a skim.

Secrets not substituted in workflow - empty or masked outputhigh

Step logs show empty string where a secret should be

GitHub ActionsIntermediate2 causes
Open runbook
Resource not accessible by integration - GITHUB_TOKEN scopeshigh

Error: Resource not accessible by integration

GitHub ActionsIntermediate2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.