Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

GitHub rejects a workflow: every step must define a uses or run key

Errorevery step must define a `uses` or `run` key

Short answer

Each item in steps has to be either an action (uses) or a shell command (run). The error means one item has neither. The usual reason is a stray hyphen that splits one step in two, or a step that only has a name, if or env. Find that item and merge or complete it.

  • Applies to GitHub Actions workflow syntax
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    The message gives no step name, so list every step item and look for one that has no uses or run line under it.

    grep -n -E "^\s*- |^\s*(uses|run):" .github/workflows/*.yml
  2. 2Match what you see, then jump to its fix

    1. 1A name: line is followed by a separate - uses: lineA hyphen was placed in front of the second key of a stepFix
    2. 2A step item contains name, if, env or with, but no uses and no runA step has only metadataFix

What does the error look like?

  • every step must define a `uses` or `run` key

Cause 1 of 2

A hyphen was placed in front of the second key of a step

1Check

A hyphen starts a new list item. If it sits before uses, the earlier name line becomes a step of its own, with no uses or run.

grep -n -B1 -E "^\s*- (uses|run):" .github/workflows/*.yml

2Fix

Remove the extra hyphen so name and uses sit in one step, at the same indentation.

steps:
  # wrong
  - name: Checkout
  - uses: actions/checkout@v4

  # right
  - name: Checkout
    uses: actions/checkout@v4

3Verify

Commit the file. The workflow appears in the Actions tab without the error.

gh workflow list

Confirmed by github.com

Did this fix it?

Cause 2 of 2

A step has only metadata

1Check

A step is either an action or a shell command. Keys such as name, if, env and with only describe the step; they do not make it one. with also only passes inputs to an action.

grep -n -A4 -E "^\s*- name:" .github/workflows/*.yml

2Fix

Add the missing uses or run, or delete a placeholder step you do not need.

- name: Install dependencies
  run: npm ci

3Verify

The workflow loads and the step runs.

gh workflow list

Confirmed by docs.github.com

Did this fix it?

How do I stop it coming back?

  • Read the diff of the workflow file before you push: every new hyphen under steps starts a new step.
  • Keep one step per list item, with all its keys under the same hyphen.
  • Delete placeholder steps instead of leaving a name alone.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Servers

docker pull or push to ghcr.io fails with 'denied'

Error response from daemon: denied

ghcr.io refuses a pull or push when Docker is not logged in, when the token lacks the package scope, or when the workflow's GITHUB_TOKEN has no packages permission or no access to that package.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.