cli/cli · error

invalid workflow: no 'on' key

Error message

invalid workflow: no 'on' key

What it means

Deeper in the same parser of `gh workflow run`: the single YAML document parsed, but scanning its top-level mapping keys (case-insensitively, since YAML 1.1 treats on/unquoted-true alike) found no 'on' key. GitHub requires `on:` to define triggers; a workflow without it is invalid, and gh cannot locate workflow_dispatch inputs without it.

Source

Thrown at pkg/cmd/workflow/run/run.go:464

						dispatchKeyNode = node
						break
					}
				}
			} else if node.Kind == yaml.ScalarNode {
				if node.Value == "workflow_dispatch" {
					dispatchKeyNode = node
					break
				}
			}
			break
		}
		if strings.EqualFold(node.Value, "on") {
			onKeyNode = node
		}
	}

	if onKeyNode == nil {
		return nil, errors.New("invalid workflow: no 'on' key")
	}

	if dispatchKeyNode == nil {
		return nil, errors.New("unable to manually run a workflow without a workflow_dispatch event")
	}

	out := []WorkflowInput{}

	m := map[string]WorkflowInput{}

	if inputsKeyNode == nil || inputsMapNode == nil {
		return out, nil
	}

	err = inputsMapNode.Decode(&m)
	if err != nil {
		return nil, fmt.Errorf("could not decode workflow inputs: %w", err)
	}

View on GitHub (pinned to 0eeec0b92e)

Solutions

1. Add the trigger block with workflow_dispatch: `on: {workflow_dispatch: {inputs: ...}}`.
2. Run actionlint on the workflow to catch structural errors before pushing.
3. Verify with `yq '.keys' .github/workflows/x.yml` that 'on' is a top-level key.
4. Remember `gh workflow run` requires the workflow_dispatch trigger specifically.

Example fix

# before (.github/workflows/deploy.yml)
name: deploy
jobs:
  build: {...}

# after
name: deploy
on:
  workflow_dispatch:
    inputs:
      env: {description: target, required: true}
jobs:
  build: {...}

yq 'has("on")' .github/workflows/deploy.yml   # must print true
yq '.on | has("workflow_dispatch")' .github/workflows/deploy.yml

When it happens

Trigger: Workflow file's root mapping contains keys like name/jobs but no 'on' (or ON/On). Note the parser compares strings.EqualFold(node.Value, "on") across scalar keys; a missing or misspelled key (e.g. 'trigger:') yields onKeyNode == nil. Follow-up error 'unable to manually run a workflow without a workflow_dispatch event' fires when `on` exists but lacks workflow_dispatch.

Common situations: Renaming `on:` to something else by mistake; quoting issues where 'on' became part of another structure; porting from other CI systems; YAML where `on:` line lost its colon.

Related errors

• invalid YAML file
• username cannot be blank
• invalid hostname
• ErrNotFound
• no default host configured; run 'gh auth login'

AI-assisted analysis of cli/cli@0eeec0b92e (2026-08-15). Data as JSON: /api/errors/c0672f2da0dab9b0. Report an issue: GitHub.