In this lesson you go from an empty repository to a pipeline that builds and tests the Orbit API on every push. You need a free account on GitLab.com, Git installed and about twenty minutes.
Create the project
- In GitLab, select New project → Create blank project.
- Name it
orbit, keep it Private and tick Initialize repository with a README. - Clone it:
$ git clone git@gitlab.com:<your-username>/orbit.git
$ cd orbit
Hosted runners on a Free account: GitLab.com runs your jobs on its own Linux runners and gives Free namespaces a monthly allowance of compute minutes. New accounts are sometimes asked to verify identity (phone or card) before the first job runs. That is an anti-abuse step, not a charge.
Your first pipeline
Create a file called .gitlab-ci.yml at the root of the repository. The leading dot and the exact name matter: GitLab looks for this file and nothing else by default.
hello:
script:
- echo "Hello from job $CI_JOB_NAME"
- echo "Running commit $CI_COMMIT_SHORT_SHA on branch $CI_COMMIT_BRANCH"
- uname -a
That is a complete pipeline: one job called hello with three shell commands. Commit and push it:
$ git add .gitlab-ci.yml
$ git commit -m "ci: first pipeline"
$ git push
Open Build → Pipelines in the left sidebar. A pipeline appears within seconds, first pending while a runner picks it up, then running, then passed. Click the job to read its log. You will see the runner preparing a container, cloning your repository and running each line of script, with the output under each command.
Notice the variables: CI_JOB_NAME, CI_COMMIT_SHORT_SHA and CI_COMMIT_BRANCH were never defined by you. GitLab injects more than a hundred predefined variables into every job. Lesson 4 covers them.
What just happened
- Your push reached GitLab.
- GitLab found
.gitlab-ci.yml, parsed it and created a pipeline with one job. - A hosted runner claimed the job, started a fresh container, cloned the commit and ran the script.
- The runner streamed the log back and reported the exit code. Exit code
0means passed; anything else means failed.
That last point is the whole contract between you and CI: a job fails when a command exits with a non-zero code. Linters, test runners and compilers all follow that rule, so they plug in without extra work.
Anatomy of a job
Every job is a top-level YAML key that is not a reserved keyword. The keys inside it describe how to run it:
unit-tests: # job name, shown in the UI
stage: test # which column it belongs to
image: node:24-alpine # container image the script runs in
before_script: # setup commands, run before script
- npm ci
script: # the actual work (required)
- npm test
after_script: # always runs, even when script fails
- echo "Job finished with status $CI_JOB_STATUS"
| Keyword | Purpose |
|---|---|
script | Shell commands to run. The only required keyword. |
image | Docker image for the job. Without it, the runner’s default image is used. |
stage | The stage the job belongs to. Defaults to test. |
before_script / after_script | Setup and cleanup around script. |
tags | Picks which runners may take the job (lesson 5). |
rules | Decides whether the job is added to the pipeline (lesson 6). |
Pin your images. image: node means “whatever is latest today”, which changes under your feet. Use a specific major version such as node:24-alpine, and in production pipelines consider a digest (node:24-alpine@sha256:…) so every run is identical.
Add the Orbit API
Let us give the pipeline something real to build. Add a minimal Node.js project. In package.json:
{
"name": "orbit-api",
"version": "1.0.0",
"type": "module",
"scripts": {
"build": "mkdir -p dist && cp -r src/* dist/",
"lint": "node --check src/server.js",
"test": "node --test"
}
}
In src/notes.js:
export function preview(text, max = 40) {
if (text.length <= max) return text;
return text.slice(0, max).trimEnd() + "…";
}
In test/notes.test.js:
import { test } from "node:test";
import assert from "node:assert/strict";
import { preview } from "../src/notes.js";
test("short notes are unchanged", () => {
assert.equal(preview("buy milk"), "buy milk");
});
test("long notes are cut with an ellipsis", () => {
assert.equal(preview("a".repeat(50), 10), "aaaaaaaaaa…");
});
Add an empty src/server.js for now and run npm install once locally so a package-lock.json exists. CI uses npm ci, which installs exactly what the lock file says and fails if it is missing.
A real build and test pipeline
Replace the contents of .gitlab-ci.yml:
stages:
- build
- test
default:
image: node:24-alpine
build-api:
stage: build
script:
- npm ci
- npm run build
artifacts:
paths:
- dist/
expire_in: 1 week
lint:
stage: test
script:
- npm ci
- npm run lint
unit-tests:
stage: test
script:
- npm ci
- npm test
What changed:
- **
stages** declares the order:buildfirst, thentest. - **
default** sets the image once for every job instead of repeating it. - **
artifacts** savesdist/whenbuild-apifinishes. Later stages download it automatically, and you can download it from the job page.expire_instops old artifacts from filling your storage. lintandunit-testsshare theteststage, so they run in parallel oncebuild-apipasses.
Push it and open the pipeline graph. You see two columns: build-api in the first, lint and unit-tests side by side in the second.
Break it on purpose
Learning to read a red pipeline is as important as writing a green one. Change the second test so it expects the wrong value:
assert.equal(preview("a".repeat(50), 10), "aaaaaaaaaa");
Push it. unit-tests turns red and the pipeline fails. Open the job log and scroll to the end:
$ npm test
✖ long notes are cut with an ellipsis
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
+ actual - expected
+ 'aaaaaaaaaa…'
- 'aaaaaaaaaa'
ℹ tests 2
ℹ pass 1
ℹ fail 1
ERROR: Job failed: exit code 1
The log names the test, shows expected versus actual and ends with the exit code that failed the job. Fix the assertion, push again and watch the pipeline turn green. Every failed pipeline you will ever debug follows this pattern: find the failing job, read the last screen of its log, reproduce locally.
Check your YAML before you push
A typo in .gitlab-ci.yml gives you a pipeline that never starts, with a yellow “yaml invalid” badge. Three ways to catch it earlier:
- Pipeline editor: Build → Pipeline editor validates the file as you type, shows the merged configuration and draws the stages before you commit.
- CI Lint: in the pipeline editor, the Validate tab simulates a pipeline for a branch.
- **The
glabCLI**: GitLab’s official command-line tool lints from your terminal and follows pipelines without opening the browser.
$ glab auth login
$ glab ci lint
Validating...
✓ CI/CD YAML is valid!
$ glab ci status
$ glab ci view
glab ci view opens an interactive view of the current branch’s pipeline where you can read logs and retry jobs.
Run a pipeline by hand
Not every pipeline comes from a push. Build → Pipelines → New pipeline lets you pick a branch and set variables for a one-off run, which is handy to re-run a deploy or test a change to the CI file. The same is possible from the CLI with glab ci run.
Exercise
A job’s script runs three commands. The second one is a test runner that exits with code 1. What happens?
Show answer
Answer: B. Each line of script runs in order and the job fails at the first command that returns a non-zero exit code. That is how test runners and linters fail a pipeline.
Exercise
build-api saves dist/ as an artifact. lint and unit-tests are in the next stage. What do they see?
Show answer
Answer: B. Every job gets a fresh clone of the commit. Artifacts from jobs in earlier stages are downloaded on top of it. node_modules was not listed as an artifact, which is why each job runs npm ci.
Key takeaways
- A pipeline is defined by
.gitlab-ci.ymlat the repository root; a push is enough to start it. - A job is a name, an image and a script. It fails when any command exits non-zero.
stagesset the order; jobs in the same stage run in parallel.artifactspass files to later stages and make them downloadable.- Validate the YAML in the pipeline editor or with
glab ci lintbefore pushing.
FAQ
Why does my pipeline not start at all?
Check the file name (.gitlab-ci.yml, with the dot), that it is on the branch you pushed, and that the YAML is valid. Also check Settings → CI/CD → General pipelines to make sure CI/CD is enabled for the project.
My job is stuck in “pending”. What does that mean?
No runner has picked it up. On GitLab.com this usually means the account needs verification or the compute minutes are used up. On self-managed GitLab it often means no runner matches the job’s tags. Lesson 5 covers runners.
Why does every job run npm ci again?
Each job starts in a fresh container with only the repository and the artifacts. That isolation is what makes results repeatable. Lesson 3 shows how a cache makes those repeated installs fast.
Can I test my pipeline locally?
Partly. glab ci lint checks the syntax and you can run the same commands in the same image with docker run -it node:24-alpine sh. For anything involving GitLab variables or runners, the fastest loop is a branch and a push.
Is .gitlab-ci.yml the only place the configuration can live?
It is the default. You can change the path in project settings, and lesson 12 shows how to pull in configuration from other files, projects and the CI/CD Catalog with include.