GitHub Actions "needs that creates a cycle"

Your job dependency graph has a loop, so there is no valid order to run the jobs. Actions rejects the workflow.

What this error means

The workflow is rejected with "You cannot use needs that creates a cycle" naming the jobs involved.

The workflow is not valid. .github/workflows/ci.yml: You cannot use 'needs' that creates a cycle: 'a' -> 'b' -> 'a'

Common causes

Mutual dependency

Job a needs b and job b needs a, which has no valid topological order.

A longer transitive loop

a needs b, b needs c, and c needs a forms a cycle across three jobs.

How to fix it

Break the dependency loop

1. Map out the needs edges and remove the back-edge.
2. Split shared work into a separate upstream job both can depend on.

jobs:
  setup: { runs-on: ubuntu-latest, steps: [{ run: ./prep }] }
  a: { needs: setup, runs-on: ubuntu-latest, steps: [{ run: ./a }] }
  b: { needs: setup, runs-on: ubuntu-latest, steps: [{ run: ./b }] }

How to prevent it

• Keep dependencies a directed acyclic graph; never have a job depend back on a descendant.
• Run actionlint to catch cycles before merge.

Related guides