How to Set a Timeout per Step in GitHub Actions

A job-level timeout caps the whole job; a step-level timeout kills just the command that hangs.

Add timeout-minutes to the specific step. When that step exceeds the limit it is cancelled and the job fails, without waiting for the job-wide budget.

Steps

• Identify the step most likely to hang (a flaky network call, an integration test).
• Add timeout-minutes: <n> to that step.
• Keep a larger job-level timeout-minutes as a backstop.

Workflow

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - name: Integration tests
        timeout-minutes: 8
        run: npm run test:integration

Gotchas

• A cancelled step still runs always() cleanup steps that follow it.
• Step timeouts are wall-clock, not CPU time.
• Latchkey runs these workflows on managed runners that are cheaper and auto-retry transient infra failures.

Related guides