Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 36 ยท Projects and Practice

Project: A Complete Web App Pipeline

Design a complete GitLab pipeline for a web app: lint, test, build an image, scan, review app, staging and manual production, then check the design with a validator you run.

In this project you put the course together. You will design the .gitlab-ci.yml for a small web application, Shelf, a Node.js service with a front end. The goal is a pipeline you would be happy to see on a real team: fast checks first, one image built once, security scans, a review app per merge request, an automatic staging deployment and a manual, protected production deployment.

GitLab cannot run on this site, so you will read and understand the complete file and then run a validator written in JavaScript that checks the properties a good pipeline file must have: every needs target exists, no cycles, no job in an unknown stage, deploy jobs have environments. The validator is a teaching stand-in with simplified rules, not GitLab's linter. In a real project, use the Pipeline editor (Build > Pipeline editor) and its Validate tab, or the CI Lint, for the real check.

Requirements

  1. Run lint and unit tests on every merge request; stop quickly on failures.
  2. Build the container image once per commit, tagged with the commit SHA.
  3. Scan source, dependencies and the image.
  4. Create a review app per merge request that is stopped when the merge request closes.
  5. Deploy main to staging automatically.
  6. Deploy to production manually, only from main, one pipeline at a time.
  7. Keep cost low: cache dependencies, skip work for docs-only changes, cancel redundant pipelines.

The pipeline file

YAML
workflow:
  auto_cancel:
    on_new_commit: interruptible
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_COMMIT_TAG

stages: [check, build, scan, review, staging, production]

default:
  image: node:22-alpine
  interruptible: true
  cache:
    key:
      files: [package-lock.json]
    paths: [.npm/]

variables:
  IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  GIT_DEPTH: "20"

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml

lint:
  stage: check
  script:
    - npm ci --cache .npm --prefer-offline
    - npm run lint
  rules:
    - changes: ["src/**/*", "package*.json", ".gitlab-ci.yml"]

unit_tests:
  stage: check
  script:
    - npm ci --cache .npm --prefer-offline
    - npm test -- --coverage
  coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'
  artifacts:
    when: always
    expire_in: 1 week
    reports:
      junit: junit.xml
  rules:
    - changes: ["src/**/*", "test/**/*", "package*.json"]

build_image:
  stage: build
  image: docker:27
  services: [docker:27-dind]
  needs: [unit_tests]
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
  script:
    - docker build --pull -t "$IMAGE" .
    - docker push "$IMAGE"

container_scanning:
  stage: scan
  needs: [build_image]
  variables:
    CS_IMAGE: $IMAGE

deploy_review:
  stage: review
  needs: [build_image]
  script: ./ci/deploy.sh review "$CI_COMMIT_REF_SLUG" "$IMAGE"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.review.example.com
    on_stop: stop_review
    auto_stop_in: 3 days
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

stop_review:
  stage: review
  variables: { GIT_STRATEGY: none }
  script: ./ci/destroy.sh review "$CI_COMMIT_REF_SLUG"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual

deploy_staging:
  stage: staging
  needs: [build_image, container_scanning]
  script: ./ci/deploy.sh staging staging "$IMAGE"
  environment:
    name: staging
    url: https://staging.example.com
  resource_group: staging
  interruptible: false
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy_production:
  stage: production
  needs: [deploy_staging]
  script: ./ci/deploy.sh production production "$IMAGE"
  environment:
    name: production
    url: https://shelf.example.com
  resource_group: production
  interruptible: false
  rules:
    - if: $CI_DEPLOY_FREEZE != null
      when: never
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual

Why it looks like this

  • workflow:rules runs merge request pipelines and default-branch pipelines but not duplicate branch pipelines (see Pipeline Efficiency Best Practices).
  • needs lets the image build start right after the tests and scans run in parallel with the review deployment. The scanner jobs come from the included templates; container_scanning here only needs its variable and an explicit needs. (The template for container scanning must be included too; the include list is shortened for readability. Add Security/Container-Scanning.gitlab-ci.yml in a real file.)
  • One image per commit, tagged by SHA, deployed everywhere (see Container Registry).
  • Production is manual, serialized by resource_group, blocked during a freeze and protected by a protected environment plus approval rules set in the project settings (see Deployment Strategies and Rollbacks).
  • Secrets such as KUBECONFIG are protected, environment-scoped file variables in the settings, never in the YAML (see CI Variables and Secrets Security).
flowchart LR
  L["lint"] --> B["build_image"]
  U["unit_tests"] --> B
  B --> C["container_scanning"]
  B --> R["deploy_review (MR only)"]
  C --> S["deploy_staging (main)"]
  S --> P{"manual"}
  P --> D["deploy_production"]

Checks first, one image, scans, then the environments in order of trust.

Stand-in: a pipeline validator

This validator takes a simplified description of the jobs (what a parser would extract from the YAML) and checks the properties listed above. Try breaking the data: rename a stage, add a needs that points nowhere, or create a cycle.

JS Pipeline validator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example computes the pipeline duration for a merge request and for a main pipeline from the job minutes, using the DAG rule from the efficiency lesson. It shows how the review job and the scan overlap.

JS How long does the pipeline take?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Your turn

Extend the project on paper (or in a real repository):

  1. Add a coverage gate: fail merge requests that lower coverage.
  2. Add a nightly scheduled pipeline that runs a DAST scan against staging.
  3. Add a rule so that a documentation-only change skips build_image and the deploy jobs.
  4. Write the project settings checklist: protected branch main, protected environment production, approval rules, variable scopes, cleanup policy.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is the image built once and deployed to every environment?

    Rebuilding for each environment can produce a different artifact; one SHA-tagged image removes that uncertainty.
  2. 2. What does the workflow:rules block in the file achieve?

    Only merge request, default branch and tag pipelines are created, so a push to an MR branch does not run twice.
  3. 3. Why does deploy_production have resource_group and interruptible: false?

    Two deploys must never overlap and a deploy should never be stopped in the middle.
  4. 4. Where should the production kubeconfig live?

    Settings variables with protection and scope keep it away from untrusted branches and non-production jobs.

Summary

  • A strong pipeline runs cheap checks first, builds one image per commit, scans it, previews merge requests and promotes the same image through staging to a gated production.
  • workflow:rules, needs, caching and interruptible keep it fast and cheap.
  • Security comes from settings as much as YAML: protected branches and environments, scoped secrets, approvals.
  • Validate pipelines with the real CI Lint; the stand-in validator shows the kinds of mistakes it catches.

Next: Project: Release Automation