GitHub Actions vs GitLab CI vs CircleCI: Jobs, Steps, and Stages Explained

I’ve been in consulting in some form or another since 2010. One thing nobody warns you about going into different customer’s environments: sometimes you don’t get to pick the CI tool (or any tooling for that matter.) The client already has one. Sometimes it’s GitHub Actions because that’s just where the code already lived. Sometimes it’s GitLab because someone five years ago wanted self-hosted runners and never looked back. I had one client running CircleCI purely because an early engineer had used it at a previous job and set it up before anyone else had an opinion.

So you end up learning three or four of these things reasonably well, not because you wanted to specialize in CI config, but because that’s what showed up on the ticket. After enough of that, you start noticing patterns within the tools and find they are mostly the same idea wearing different names. Once you see the shared shape, switching between them gets a lot less annoying.

The part that’s the same everywhere

Every one of these systems has the same four layers:

Something triggers a run: a push, a pull request, a tag, a cron schedule, someone clicking a button.

That triggers the whole run: this is the “pipeline” or the “workflow run,” depending on the tool.

Inside the run, units of work happen on their own machines. These are almost always called jobs, across all three tools.

Inside a job, individual commands run one after another. These are steps, or a script: list.

The two layers worth understanding are the job and the step, because everything else is just orchestration wrapped around them.

A step is one command inside a job. Steps run in order, and because they’re on the same machine, they share a filesystem. Step one runs npm install, step two can use those packages, no extra work required.

A job gets its own fresh machine or container. This is the one that trips people up when they’re new to a tool: jobs don’t share anything. You have to check out the code again in every single job, because as far as that job is concerned, nothing existed before it started. If you need to move a file from one job to another, you’re reaching for artifacts or a cache, not just assuming it’ll be there.

I’ve seen engineers spend an hour debugging why their test job “lost” a file that the build job created, before realizing the two jobs never shared a filesystem to begin with. It’s not a bug. It’s the whole point of running jobs in isolation.

Where the naming splits

Two things in that table have burned me personally.

“Workflow” doesn’t mean the same thing in GitHub and CircleCI. In GitHub, the workflow is the whole file, top to bottom. In CircleCI, a workflow is a layer inside the config that arranges jobs, which means CircleCI has an extra level of nesting: pipeline, then workflow, then jobs, then steps. I once spent a confusing twenty minutes on a call with a CircleCI-only client because I kept using “workflow” the GitHub way.

And “stage” is basically a GitLab thing. GitHub and CircleCI don’t have a stage concept at all.

Stages versus dependency graphs

This is the split that changes how you think about writing the config, not just what you call things.

GitLab has named stages. You declare an ordered list, build, test, deploy, whatever fits, and assign each job to one. Every job in a stage runs in parallel, and the next stage doesn’t start until the whole previous stage finishes. It reads almost like a checklist, which is nice when you’re new to the codebase and just want to know what happens and in what order.

GitHub Actions and CircleCI skip stages entirely. Instead, each job declares which other jobs it needs to finish first, needs: in GitHub, requires: in CircleCI, and that builds a dependency graph. A job can start the second its specific dependencies are done, without waiting on unrelated jobs to clear some stage that has nothing to do with it. On a big pipeline with a lot of independent jobs, that difference in wall-clock time adds up.

Worth knowing if you’re moving between the two models: GitLab added needs: too, so a job can now jump ahead of the normal stage order if its actual dependencies are satisfied earlier. The two approaches are drifting toward each other. GitLab still centers on stages by default, though, and that’s usually the mental model you’ll find in an existing GitLab config.

The same two-job pipeline, three ways

Build, then test, expressed in each tool:

GitHub Actions

1
name: CI
2
on: [push]
3
jobs:
4
  build:
5
    runs-on: ubuntu-latest
6
    steps:
7
      - uses: actions/checkout@v4
8
      - run: npm ci
9
      - run: npm run build
10
  test:
11
    runs-on: ubuntu-latest
12
    needs: build
13
    steps:
14
      - uses: actions/checkout@v4
15
      - run: npm ci
16
      - run: npm test

GitLab CI

1
stages:
2
  - build
3
  - test
4

5
build-job:
6
  stage: build
7
  script:
8
    - npm ci
9
    - npm run build
10

11
test-job:
12
  stage: test
13
  script:
14
    - npm ci
15
    - npm test

CircleCI

1
version: 2.1
2
jobs:
3
  build:
4
    docker:
5
      - image: cimg/node:20.0
6
    steps:
7
      - checkout
8
      - run: npm ci
9
      - run: npm run build
10
  test:
11
    docker:
12
      - image: cimg/node:20.0
13
    steps:
14
      - checkout
15
      - run: npm ci
16
      - run: npm test
17
workflows:
18
  build-and-test:
19
    jobs:
20
      - build
21
      - test:
22
          requires:
23
            - build

Same shape all three times: checkout, install, run a command, wait for the first job before starting the second. GitHub says needs, CircleCI says requires, GitLab just puts you in a later stage. Once you’ve written this pattern in one tool, translating it to the other two is mostly a vocabulary lookup, not new thinking.

What helps when you land somewhere new

When I show up at a client and open their CI config for the first time, I don’t try to memorize the whole file. I look for three things: where the config file lives (tells me which tool I’m in before I even read it), whether jobs are isolated or sharing a runner (usually isolated, but self-hosted setups sometimes get creative), and how the ordering is expressed, stage or dependency graph.

None of that takes long to check once you know what you’re looking for, and that’s really the payoff of learning the shared model in the first place. The next client can be running a tool I’ve never touched, and I’m not starting from zero. I’m just mapping a job to a job, a step to a step, and figuring out where their stage or dependency graph lives. The vocabulary changes. The thing I’m looking for doesn’t.