GitLab CI Setup

You are a DevOps engineer setting up continuous integration for a GitLab project. The user wants to create a .gitlab-ci.yml pipeline configuration file that defines build, test, and deploy stages.

What to check first

• Verify GitLab project exists and you have push access to the repository root
• Run git config --get remote.origin.url to confirm the GitLab remote is configured
• Check if the project has a .gitignore that won't exclude .gitlab-ci.yml

Steps

1. Navigate to your project root directory where .git exists
2. Create the .gitlab-ci.yml file in the repository root (not in a subdirectory)
3. Define the stages keyword at the top to organize pipeline phases (e.g., build, test, deploy)
4. Create a job under each stage using the stage name; each job must have a script section with shell commands
5. Set image to specify the Docker image for job execution (e.g., image: node:18 for Node.js projects)
6. Add only or rules to control when jobs run (e.g., only on main branch or merge requests)
7. Use artifacts to pass files between jobs (e.g., compiled binaries or test reports)
8. Commit and push the .gitlab-ci.yml file; GitLab will automatically trigger the pipeline
9. Navigate to the project's CI/CD > Pipelines page in GitLab UI to monitor execution

Code

# .gitlab-ci.yml
# Define pipeline stages
stages:
  - build
  - test
  - deploy

# Global variables available to all jobs
variables:
  NODE_ENV: production
  REGISTRY: registry.gitlab.com

# Build stage: compile or prepare artifacts
build:
  stage: build
  image: node:18-alpine
  before_script:
    - npm ci
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
      - node_modules/
    expire_in: 1 hour
  only:
    - merge_requests
    - main
    - develop

# Test stage: run unit and integration tests
test:unit:
  stage: test
  image: node:18-alpine
  dependencies:
    - build
  script:
    - npm ci
    - npm run test:unit
  coverage: '/Coverage: \d+\.\d+%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
  only:
    - merge_requests
    - main

# Lint stage: check code quality
test:lint:
  stage: test
  image: node:18-alpine
  script:
    - npm ci
    - npm run lint
  allow_failure: true
  only:
    - merge_requests

# Deploy stage: push to production
deploy:production:
  stage: deploy

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change