gitlab-ci

GitLab CI/CD

使用 GitLab 集成的 CI/CD 系统自动化软件交付流水线。

何时使用此技能

在以下情况下使用此技能：

• 在 GitLab 中设置 CI/CD 流水线
• 配置 GitLab 运行器（共享或自托管）
• 创建多阶段部署流水线
• 实施 GitLab Auto DevOps
• 管理 CI/CD 变量和机密

前提条件

• GitLab 仓库（gitlab.com 或自托管）
• YAML 基础知识
• 对于自托管运行器：Linux 服务器或 Kubernetes 集群

流水线配置

在仓库根目录中创建 .gitlab-ci.yml：

stages:
  - build
  - test
  - deploy

variables:
  NODE_VERSION: "20"

build:
  stage: build
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm test
  coverage: '/Coverage: \d+\.\d+%/'

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

作业配置

基于规则的执行

deploy:
  script: ./deploy.sh
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: never
    - when: on_success

并行作业

test:
  stage: test
  parallel: 3
  script:
    - npm test -- --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL

矩阵构建

test:
  stage: test
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
        OS: ["alpine", "slim"]
  image: node:${NODE_VERSION}-${OS}
  script:
    - npm test

缓存

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/
  policy: pull-push

build:
  cache:
    key: build-cache
    paths:
      - .cache/
    policy: pull

构件

build:
  artifacts:
    paths:
      - dist/
      - coverage/
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura.xml
    expire_in: 1 week
    when: always

环境和部署

deploy_staging:
  stage: deploy
  script:
    - deploy --env staging
  environment:
    name: staging
    url: https://staging.example.com
    on_stop: stop_staging

stop_staging:
  stage: deploy
  script:
    - undeploy --env staging
  environment:
    name: staging
    action: stop
  when: manual

Docker 构建

build_image:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

GitLab 运行器

安装运行器

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

# Register runner
sudo gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token TOKEN \
  --executor docker \
  --docker-image alpine:latest

运行器配置

# /etc/gitlab-runner/config.toml
[[runners]]
  name = "docker-runner"
  url = "https://gitlab.com/"
  token = "TOKEN"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = true
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]

运行器标签

build:
  tags:
    - docker
    - linux
  script:
    - make build

CI/CD 变量

受保护的变量

在 Settings > CI/CD > Variables 中定义：

• AWS_ACCESS_KEY_ID（受保护、已屏蔽）
• AWS_SECRET_ACCESS_KEY（受保护、已屏蔽）

使用变量

deploy:
  script:
    - aws s3 sync dist/ s3://$S3_BUCKET
  variables:
    AWS_DEFAULT_REGION: us-east-1

Include 和 Extend

包含模板

include:
  - template: Security/SAST.gitlab-ci.yml
  - project: 'group/shared-ci'
    file: '/templates/deploy.yml'
  - local: '/ci/jobs.yml'

扩展作业

.base_job:
  image: node:20
  before_script:
    - npm ci

build:
  extends: .base_job
  script:
    - npm run build

test:
  extends: .base_job
  script:
    - npm test

多项目流水线

trigger_downstream:
  stage: deploy
  trigger:
    project: group/downstream-project
    branch: main
    strategy: depend

常见问题

问题：流水线卡住

问题：作业一直处于等待状态 解决方案：检查运行器是否可用，以及标签是否匹配

问题：Docker-in-Docker 失败

问题：无法连接到 Docker 守护进程 解决方案：使用 docker:dind 服务，并正确配置 TLS

问题：缓存无法使用

问题：作业之间未命中缓存 解决方案：检查缓存键，并确保运行器共享分布式缓存

最佳实践

• 对于复杂条件，使用 rules 代替 only/except
• 充分利用 GitLab 内置的安全扫描模板
• 使用作业依赖项优化流水线速度
• 为合并请求实现评审应用
• 积极缓存依赖项
• 使用构件在不同阶段之间传递数据

相关技能

• github-actions - GitHub CI/CD 替代方案
• argocd-gitops - GitOps 部署
• container-registries - 容器仓库管理