Pipeline, job, runner, artifact, environment
Beginner Core Git
Why this matters
Every conversation about automation uses these words, and most of them mean something slightly different on each platform. Ten minutes here makes the rest of the section, and every pipeline page you ever open, readable.
How the pieces fit
The words
| Word | Means |
|---|---|
| Pipeline | Everything that runs for one trigger: all the stages and jobs together |
| Stage | A phase, such as check or deploy; stages run one after another |
| Job | One unit of work, such as tests; jobs in the same stage run at the same time |
| Step | One command inside a job (GitHub's word; GitLab calls these script lines) |
| Runner | The machine that executes a job, usually a fresh container from an image |
| Image | The starting environment for a job: python:3.13-slim, node:20 |
| Artifact | A file a job produces and keeps: a report, a built site, a test result |
| Cache | Files kept between runs to save time, such as downloaded dependencies |
| Variable | A value given to a job, sometimes secret (lesson 9.12) |
| Environment | A named place a job deploys to: staging, production (lesson 14.6) |
| Deployment | One act of putting a build into an environment |
| Status check | The pipeline result as seen by the merge request (lesson 14.7) |
GitLab and GitHub, side by side
| Concept | GitLab | GitHub |
|---|---|---|
| The whole run | Pipeline | Workflow run |
| The file | .gitlab-ci.yml |
.github/workflows/*.yml |
| A phase | Stage | Expressed with needs between jobs |
| A unit of work | Job | Job |
| A command | A line under script |
A step with run |
| A reusable piece | include, templates |
An action, used with uses |
| The machine | Runner | Runner |
| Kept files | Artifact | Artifact |
| A secret | CI/CD variable | Actions secret |
The terminology map has the full comparison.
Artifacts, briefly
An artifact is how a job hands something to a human or to a later job. Three common uses:
- A built site, passed to the deployment job. The site you are reading is published this way.
- A test or coverage report, downloadable from the job page, which is where "the tests passed but what did they check?" is answered.
- A rendered preview of documentation, which lets a reviewer read the change as a page rather than as a diff.
Artifacts expire, usually after days or weeks, so a link to one in a review comment goes stale. Say what it showed, not just where it was.
Why a job fails when your machine is fine
This is the most common confusion for someone new to CI, and it has four usual causes:
| Cause | How it shows |
|---|---|
| Different version | The image pins Python 3.12 and you have 3.13, or the reverse |
| A missing dependency | It is installed on your machine and not in the image |
| A file you never committed | The runner clones the repository, and it does not have your uncommitted work |
| A different working directory or environment variable | Paths and settings differ from your shell |
The third is worth remembering: the runner only sees what is committed and pushed. "It works on my machine" is often literally true and means a file is missing from the commit.
Reading a pipeline page
Whatever the platform, the same three questions:
- Which job failed? The pipeline page tells you this and nothing else useful.
- Where in that job? Open it and find the failed step or the end of the log.
- Is it mine? Does the error name a file I changed, and does the same job fail on
main?
How to do it
The vocabulary is on the platform, but the most useful command is the one that shows you what the jobs actually run:
$ cat .gitlab-ci.ymlEvery script line is a command you can run yourself, in your own shell, before pushing.
The GitLab Workflow and GitHub Actions extensions list runs and jobs in the sidebar and open logs in an editor tab, which is easier to search than a browser.
Pipeline status appears on the branch and in the merge or pull request tool window, with links to the job logs.
Build → Pipelines lists runs; clicking one shows the stages as columns and the jobs as entries. Build → Jobs lists jobs across all pipelines, which is how you find a job that fails intermittently. Build → Artifacts lists what has been kept.
Actions lists workflow runs; a run shows its jobs, and a job shows its steps with collapsible logs. Artifacts are listed at the bottom of the run summary page.
Common mistakes
- Confusing stage and job. The stage failed because a job in it did; the job is where the log is.
- Thinking a skipped job failed. Skipped means an earlier stage stopped, or a rule excluded it.
- Expecting the runner to see uncommitted files. It clones what you pushed.
- Linking to an artifact in a review comment and assuming it will still be there next month.
- Assuming a green pipeline means the change is correct. It means the checks that exist passed.
Try it yourself
Goal: map the vocabulary onto a real pipeline.
- Open your project's most recent pipeline or workflow run.
- Write down its stages (or job dependencies), its jobs, and which image each job uses.
- Find one job's log and identify where the setup ends and the real work begins.
- Find any artifacts the run produced, and note when they expire.
- Take one
scriptorrunline and execute it in your own terminal.
Expected result: a description of the pipeline in the words from this lesson, and one of its checks running on your machine.
Show solution
Step 5 is the habit worth taking away. A pipeline is not magic infrastructure: it is a list of commands someone wrote down, running on a clean machine. Once you have run one of them yourself, the whole thing stops being opaque.