How-To Guide · GitLab CI/CD

How to Set Up a GitLab CI/CD Pipeline — Step by Step

A GitLab pipeline is defined by a single file called `.gitlab-ci.yml` in the root of your repository. Commit that file and GitLab starts running pipelines on every push — there is no separate service to enable. This guide takes you from an empty repository to a working build-test-deploy pipeline with caching, artefacts and a manual production gate, then covers the two things that decide whether the pipeline stays useful: keeping it under ten minutes, and keeping compute-minute consumption off your invoice.

Steps

• Confirm your runner situation before you write any YAML: Jobs need a runner to execute on. On GitLab.com, shared GitLab-hosted runners are available immediately and are metered as compute minutes — 400 a month on Free, 10,000 on Premium, 50,000 on Ultimate. That is enough to start, but check it now rather than after a surprise. On a Self-Managed instance there are no shared runners by default and you must register your own before anything runs. Go to Settings → CI/CD → Runners in your project to see what is available to you.
  • Free tier gets 400 compute minutes a month — a single 4-minute job run 30 times a day exceeds that in under four days
  • Self-hosted runners consume zero compute minutes on every tier, including Free
  • For India-based teams a runner VM in an India region also cuts job start latency noticeably
  • Register a runner with `gitlab-runner register`, then pick the Docker executor unless you have a specific reason not to
• Create .gitlab-ci.yml with your stages: Add a file named `.gitlab-ci.yml` to the repository root. Declare a `stages` list first — stages run strictly in order, and a stage begins only when the previous one has fully succeeded. Three stages cover almost every project: build, test, deploy. Set a default `image` at the top so every job runs in a predictable container; without it you inherit whatever the runner defaults to, which is a common source of "it works on my machine but not in CI".
  • Start with `stages: [build, test, deploy]` — resist adding more until something genuinely needs it
  • Set a top-level `image:` pinned to a specific version tag, not `latest`, so builds are reproducible
  • GitLab validates the file — use the CI Lint tool under Build → Pipeline editor before pushing
  • The file lives in the repo, so every commit carries the exact build process that produced it
• Write the build job and save its output as artifacts: A job is a named block with a `stage` and a `script` list of shell commands. Your build job installs dependencies and compiles or bundles the application. Whatever it produces that later stages need — a `dist/` folder, a compiled binary, a package — must be declared under `artifacts: paths:`, because each job runs in a fresh container and nothing carries over implicitly. Set `expire_in` on artefacts too, or they accumulate against your storage quota indefinitely.
  • Artifacts are how output moves between stages — without declaring them, the test stage sees an empty workspace
  • Always set `expire_in: 1 week` (or shorter) on routine build artefacts; only release artefacts need long retention
  • Artefacts are downloadable from the pipeline view, which is useful for debugging a failed deploy
  • Keep artefact paths tight — uploading `node_modules` as an artefact is a classic slow-pipeline mistake
• Add cache so you are not re-downloading dependencies every run: Cache is the single biggest lever on pipeline duration and it is the step teams most often skip. Declare a `cache:` block with a `key` and the directories to persist — `node_modules/`, `.m2/repository`, `vendor/bundle`, whatever your ecosystem uses. Key the cache on your lockfile so it invalidates when dependencies actually change: `key: files: [package-lock.json]`. Done properly this routinely takes a pipeline from fourteen minutes to four.
  • Cache is for dependencies you can rebuild; artifacts are for output you need to keep — do not confuse them
  • Key the cache on the lockfile so it invalidates automatically on a dependency change
  • Use `policy: pull` on jobs that only read the cache, so they do not spend time re-uploading it
  • Measure before and after — if the cache is not cutting duration, it is misconfigured
• Split the test stage into parallel jobs: Jobs within the same stage run in parallel, which is free speed most teams leave on the table. Instead of one job that runs lint, unit tests and integration tests sequentially, declare three jobs all with `stage: test`. They start together and the stage takes as long as the slowest one rather than the sum. Add security scanning here too — GitLab includes SAST and secret detection on every tier, enabled by including the relevant templates.
  • Three parallel 3-minute jobs finish in 3 minutes, not 9
  • Include `Jobs/SAST.gitlab-ci.yml` and `Jobs/Secret-Detection.gitlab-ci.yml` via `include: template:` — both are available on Free
  • Use `allow_failure: true` on a new scanner while you tune it, so it reports without blocking anyone
  • Publish test reports with `artifacts: reports:` so results appear directly in the merge request
• Control when jobs run with rules: By default every job runs on every push, which wastes both wall-clock time and metered compute minutes. `rules:` fixes that. Run the full test suite on merge requests and on the default branch; skip deploys on feature branches; skip jobs entirely when only documentation changed. This is usually where the largest compute-minute saving comes from on a busy repository.
  • `rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"` scopes a job to merge requests
  • Use `changes:` to skip a job when its relevant files were not touched — a docs-only commit need not rebuild containers
  • `workflow:` rules at the top of the file can stop duplicate pipelines running for both a branch push and its merge request
  • Every job you correctly skip is compute minutes you do not buy back at 0 per 1,000
• Add the deploy stage with a manual production gate: Deploy jobs are ordinary jobs that talk to your target — a cloud CLI, kubectl, an SSH rsync. Two things make them safe. Attach an `environment:` name so GitLab tracks what is deployed where and gives you a rollback view. And put `when: manual` on the production job, so the pipeline runs all the way to a ready-to-deploy state and then waits for a human click. Staging can and should deploy automatically.
  • `environment: name: production` gives you deployment history and a one-click rollback view
  • Store credentials as masked, protected CI/CD variables under Settings → CI/CD → Variables — never in the YAML
  • Mark deploy variables "protected" so they are only exposed to protected branches
  • `when: manual` on production is the line between continuous delivery and continuous deployment — choose deliberately
• Push, watch the first run, and tune duration: Commit and push. GitLab picks the file up immediately and the pipeline appears under Build → Pipelines. The first run will almost certainly fail somewhere — usually a missing dependency in the container image or a path assumption that only held locally. Read the job log, fix, push again. Once it is green, look at the duration breakdown per job and attack whatever dominates it, because a pipeline developers stop waiting for stops doing its job.
  • Under ten minutes for the merge-request pipeline is the target that keeps developers engaged with it
  • The pipeline view shows per-job duration — optimise the slowest job, not the one that looks messiest
  • Add `interruptible: true` so a new push cancels the superseded pipeline instead of running both
  • Set required approvals and "pipelines must succeed" in merge request settings once it is stable, so the pipeline actually gates merges