GitLab CI/CD Commands Reference & Best Practices

# Clone repository
git clone https://gitlab.com/username/project.git
cd project

# Create branch
git checkout -b feature/my-feature

# Add changes
git add .

# Commit
git commit -m "Add feature"

# Push to GitLab
git push origin feature/my-feature

# Create merge request (from command line)
git push origin feature/my-feature -o merge_request.create

# Stages (порядок выполнения)
stages:
  - build
  - test
  - deploy

# Global variables
variables:
  VERSION: "1.0"

# Default for all jobs
default:
  image: ubuntu:20.04

# Jobs
build_job:
  stage: build
  script:
    - echo "Building..."

stages:
  - build
  - test
  - deploy

variables:
  VERSION: "1.0"
  LOG_FILE: "build-${CI_COMMIT_BRANCH}-${CI_COMMIT_SHORT_SHA}.log"

default:
  image: ubuntu:20.04
  retry:
    max: 2
  timeout: 1 hour

build:
  stage: build
  script:
    - echo "Building v${VERSION}..."
    - mkdir -p dist
    - echo "Built" > dist/status.txt
  artifacts:
    paths:
      - dist/
    expire_in: 1 week
  rules:
    - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"'

test_unit:
  stage: test
  needs: ["build"]
  script:
    - npm test
  cache:
    paths:
      - node_modules/

test_lint:
  stage: test
  needs: ["build"]
  script:
    - npm run lint

deploy_dev:
  stage: deploy
  environment:
    name: development
    url: https://dev.example.com
  script:
    - ./deploy.sh dev
  rules:
    - if: '$CI_COMMIT_BRANCH == "develop"'

deploy_prod:
  stage: deploy
  environment:
    name: production
    url: https://example.com
  script:
    - ./deploy.sh prod
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual

# Run on main branch
rules:
  - if: '$CI_COMMIT_BRANCH == "main"'

# Run on any branch except main
rules:
  - if: '$CI_COMMIT_BRANCH != "main"'

# Run on merge request
rules:
  - if: '$CI_MERGE_REQUEST_IID'

# Manual trigger
rules:
  - when: manual

# Never run
rules:
  - when: never

# Conditional variables
rules:
  - if: '$CI_COMMIT_BRANCH == "main"'
    variables:
      ENV: "production"
  - if: '$CI_COMMIT_BRANCH == "develop"'
    variables:
      ENV: "staging"

# Save artifacts
artifacts:
  paths:
    - dist/
    - build/output.txt
  expire_in: 1 week

# Using artifacts from previous job
needs: ["build"]
script:
  - cat dist/output.txt

# Download artifacts
# From UI: CI/CD → Pipelines → Job → Download artifacts

# Cache dependencies
cache:
  paths:
    - node_modules/
    - vendor/
  key: "$CI_COMMIT_REF_SLUG"

# Cache between stages
default:
  cache:
    paths:
      - .cache/

# Use specific Docker image
image: node:16

# Use different image per job
build:
  image: ubuntu:20.04

test:
  image: node:16

# Docker in Docker
image: docker:latest
services:
  - docker:dind
script:
  - docker build -t my-app .
  - docker push my-registry/my-app

test:
  stage: test
  script:
    - npm test -- --version=$VERSION
  parallel:
    matrix:
      - VERSION: ["12", "14", "16"]

# Creates 3 parallel jobs:
# test[12], test[14], test[16]

deploy:
  stage: deploy
  environment:
    name: production
    url: https://example.com
    deployment_tier: production
  script:
    - ./deploy.sh

deploy_manual:
  stage: deploy
  environment:
    name: production
  script:
    - ./deploy.sh
  when: manual

# Retry on failure
retry:
  max: 2
  when:
    - api_failure
    - runner_system_failure

# Timeout
timeout: 1 hour

# Only for specific job
job:
  retry: 1
  timeout: 30 minutes

build:
  stage: build
  script:
    - npm run build

test:
  stage: test
  needs: ["build"]
  script:
    - npm test

test_unit:
  stage: test
  script:
    - npm test

test_integration:
  stage: test
  script:
    - npm test:integration

# Both run in parallel

build:
  stage: build
  script:
    - npm run build

test_unit:
  stage: test
  needs: ["build"]
  script:
    - npm test

test_integration:
  stage: test
  needs: ["test_unit"]
  script:
    - npm test:integration

deploy_dev:
  stage: deploy
  environment:
    name: development
  script:
    - ./deploy.sh dev
  rules:
    - if: '$CI_COMMIT_BRANCH == "develop"'

deploy_prod:
  stage: deploy
  environment:
    name: production
  script:
    - ./deploy.sh prod
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual

# ✅ DO
stages:
  - build
  - test
  - deploy

variables:
  VERSION: "1.0"

default:
  image: ubuntu:20.04
  retry:
    max: 2
  timeout: 1 hour

build:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

# ❌ DON'T
script:
  - apt-get update
  - apt-get install -y npm
  - npm install
  - npm test
  - npm run build
  # Everything in one job!

# Install Runner
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt-get install gitlab-runner

# Register Runner
sudo gitlab-runner register
  # URL: https://gitlab.com
  # Token: (from project CI/CD settings)
  # Description: my-runner
  # Tags: my-tag
  # Image: ubuntu:20.04

# Start Runner
sudo gitlab-runner start

# Check status
sudo gitlab-runner status

# View config
sudo gitlab-runner verify

# List runners
gitlab-runner list

# Remove runner
sudo gitlab-runner unregister --name my-runner

# View pipeline in web UI
# Project → CI/CD → Pipelines

# View job logs
# Click on job → See full output

# Check config syntax
# Use "Validate" button in Pipeline Editor

# Common errors
# - Indentation issues (YAML is strict)
# - Wrong variable names
# - Image not found
# - Script failed (non-zero exit code)

# Add status badge to README
[![pipeline status](https://gitlab.com/NAMESPACE/PROJECT/badges/BRANCH/pipeline.svg)](https://gitlab.com/NAMESPACE/PROJECT/-/commits/BRANCH)

[![coverage report](https://gitlab.com/NAMESPACE/PROJECT/badges/BRANCH/coverage.svg)](https://gitlab.com/NAMESPACE/PROJECT/-/commits/BRANCH)