gitlab-ci

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitLab CI/CD

Automate your software delivery pipeline with GitLab's integrated CI/CD system.

借助GitLab集成的CI/CD系统，实现软件交付流水线自动化。

When to Use This Skill

何时使用该技能

Use this skill when:

Setting up CI/CD pipelines in GitLab
Configuring GitLab runners (shared or self-hosted)
Creating multi-stage deployment pipelines
Implementing GitLab Auto DevOps
Managing CI/CD variables and secrets

在以下场景使用该技能：

在GitLab中搭建CI/CD流水线
配置GitLab运行器（共享或自托管）
创建多阶段部署流水线
落地GitLab Auto DevOps
管理CI/CD变量与密钥

Prerequisites

前置条件

GitLab repository (gitlab.com or self-hosted)
Basic understanding of YAML
For self-hosted runners: Linux server or Kubernetes cluster

GitLab仓库（gitlab.com或自托管）
具备YAML基础认知
自托管运行器：Linux服务器或Kubernetes集群

Pipeline Configuration

流水线配置

Create

.gitlab-ci.yml

in repository root:

yaml

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

在仓库根目录创建

.gitlab-ci.yml

：

yaml

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

Job Configuration

任务配置

Rules-Based Execution

基于规则的执行

yaml

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

yaml

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

Parallel Jobs

并行任务

yaml

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

yaml

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

Matrix Builds

矩阵构建

yaml

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

yaml

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

Caching

缓存配置

yaml

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

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

yaml

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

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

Artifacts

制品管理

yaml

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

yaml

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

Environments and Deployments

环境与部署

yaml

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

yaml

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 Builds

Docker构建

yaml

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

yaml

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 Runners

GitLab运行器

Install Runner

安装运行器

bash

undefined

bash

undefined

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

undefined

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

undefined

Runner Configuration

运行器配置

toml

undefined

toml

undefined

/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"]

undefined

undefined

Runner Tags

运行器标签

yaml

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

yaml

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

CI/CD Variables

CI/CD变量

Protected Variables

受保护变量

Define in Settings > CI/CD > Variables:

```
AWS_ACCESS_KEY_ID
```
(protected, masked)
```
AWS_SECRET_ACCESS_KEY
```
(protected, masked)

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

```
AWS_ACCESS_KEY_ID
```
（受保护、掩码处理）
```
AWS_SECRET_ACCESS_KEY
```
（受保护、掩码处理）

Using Variables

变量使用

yaml

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

yaml

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

Include and Extend

引用与继承

Include Templates

引用模板

yaml

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

yaml

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

Extend Jobs

继承任务

yaml

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

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

test:
  extends: .base_job
  script:
    - npm test

yaml

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

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

test:
  extends: .base_job
  script:
    - npm test

Multi-Project Pipelines

多项目流水线

yaml

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

yaml

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

Common Issues

常见问题

Issue: Pipeline Stuck

问题：流水线停滞

Problem: Jobs stay pending Solution: Check runner availability and tags matching

现象：任务一直处于待处理状态 解决方案：检查运行器可用性及标签匹配情况

Issue: Docker-in-Docker Fails

问题：Docker-in-Docker失败

Problem: Cannot connect to Docker daemon Solution: Use

docker:dind

service with proper TLS configuration

现象：无法连接Docker守护进程 解决方案：使用

docker:dind

服务并配置正确的TLS设置

Issue: Cache Not Working

问题：缓存不生效

Problem: Cache misses between jobs Solution: Verify cache key and ensure runners share distributed cache

现象：任务间缓存命中失败 解决方案：验证缓存密钥，确保运行器共享分布式缓存

Best Practices

最佳实践

Use
```
rules
```
instead of
```
only/except
```
for complex conditions
Leverage GitLab's built-in security scanning templates
Use job dependencies to optimize pipeline speed
Implement review apps for merge requests
Cache dependencies aggressively
Use artifacts for passing data between stages

复杂条件下使用
```
rules
```
替代
```
only/except
```
利用GitLab内置的安全扫描模板
使用任务依赖优化流水线速度
为合并请求实现Review Apps
积极缓存依赖项
使用制品在阶段间传递数据

gitlab-ci

Original

Translation

GitLab CI/CD

GitLab CI/CD

When to Use This Skill

何时使用该技能

Prerequisites

前置条件

Pipeline Configuration

流水线配置

Job Configuration

任务配置

Rules-Based Execution

基于规则的执行

Parallel Jobs

并行任务

Matrix Builds

矩阵构建

Caching

缓存配置

Artifacts

制品管理

Environments and Deployments

环境与部署

Docker Builds

Docker构建

GitLab Runners

GitLab运行器

Install Runner

安装运行器

Download and install

下载并安装

Register runner

注册运行器

Runner Configuration

运行器配置

/etc/gitlab-runner/config.toml

/etc/gitlab-runner/config.toml

Runner Tags

运行器标签

CI/CD Variables

CI/CD变量

Protected Variables

受保护变量

Using Variables

变量使用

Include and Extend

引用与继承

Include Templates

引用模板

Extend Jobs

继承任务

Multi-Project Pipelines

多项目流水线

Common Issues

常见问题

Issue: Pipeline Stuck

问题：流水线停滞

Issue: Docker-in-Docker Fails

问题：Docker-in-Docker失败

Issue: Cache Not Working

问题：缓存不生效

Best Practices

最佳实践

Related Skills

相关技能