Estructura de .gitlab-ci.yml

El archivo .gitlab-ci.yml en la raiz de tu repositorio define que ejecutar, cuando y como.

Estructura minima

test:
  script:
    - echo "Hello CI/CD"

Eso es un pipeline valido. Un job llamado test que ejecuta un echo.

Stages

Los stages definen el orden de ejecucion. Jobs del mismo stage corren en paralelo.

stages:
  - build
  - test
  - deploy

compile:
  stage: build
  script:
    - npm run build

unit_tests:
  stage: test
  script:
    - npm test

lint:
  stage: test  # Corre en paralelo con unit_tests
  script:
    - npm run lint

production:
  stage: deploy
  script:
    - ./deploy.sh

Images y Services

default:
  image: node:20-alpine

test:
  services:
    - postgres:16-alpine
  variables:
    POSTGRES_DB: test_db
    POSTGRES_USER: runner
    POSTGRES_PASSWORD: secret
  script:
    - npm run test:integration

• image: Contenedor principal donde corre el job
• services: Contenedores adicionales accesibles por red (databases, redis, etc.)
• El servicio es accesible por su nombre: postgres en este caso

before_script y after_script

default:
  before_script:
    - echo "Setup comun"
  after_script:
    - echo "Cleanup comun"

test:
  before_script:
    - npm ci  # Sobreescribe el default
  script:
    - npm test

• before_script: Se ejecuta antes de script
• after_script: Se ejecuta siempre, incluso si el job falla
• Se pueden definir a nivel global (default) o por job

Templates con extends

.node_template:
  image: node:20-alpine
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/

test:
  extends: .node_template
  script:
    - npm ci
    - npm test

lint:
  extends: .node_template
  script:
    - npm ci
    - npm run lint

Jobs que empiezan con . son templates (no se ejecutan).

Include

Reutiliza configuraciones de otros archivos:

include:
  # Archivo local
  - local: .gitlab/ci/test.yml

  # Desde otro proyecto
  - project: mi-grupo/ci-templates
    ref: main
    file: /templates/node.yml

  # URL remota
  - remote: "https://example.com/ci-template.yml"

  # Template de GitLab
  - template: Security/SAST.gitlab-ci.yml

needs (DAG)

Por defecto, los jobs respetan el orden de stages. Con needs puedes crear un DAG (grafo dirigido):

stages:
  - build
  - test
  - deploy

build_api:
  stage: build
  script:
    - make build-api

build_frontend:
  stage: build
  script:
    - make build-frontend

test_api:
  stage: test
  needs: [build_api]  # No espera a build_frontend
  script:
    - make test-api

test_frontend:
  stage: test
  needs: [build_frontend]
  script:
    - make test-frontend

deploy:
  stage: deploy
  needs: [test_api, test_frontend]
  script:
    - make deploy

needs permite que los jobs empiecen tan pronto como sus dependencias terminen, sin esperar todo el stage.

Validar el archivo

# Con la CLI de GitLab
gitlab-ci-lint .gitlab-ci.yml

# O en la UI: CI/CD > Editor > Validate

---

Siguiente: Capitulo 8: Variables, Rules y Environments →