gitlab-ci-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitLab CI - Best Practices

GitLab CI - 最佳实践

Optimize GitLab CI/CD pipelines for performance, reliability, and maintainability.

针对性能、可靠性和可维护性优化GitLab CI/CD流水线。

Pipeline Optimization

流水线优化

Use DAG with Needs

结合Needs使用DAG

yaml

stages:
  - build
  - test
  - deploy

build:frontend:
  stage: build
  script: npm run build:frontend

build:backend:
  stage: build
  script: npm run build:backend

test:frontend:
  stage: test
  needs: ["build:frontend"]
  script: npm run test:frontend

test:backend:
  stage: test
  needs: ["build:backend"]
  script: npm run test:backend

deploy:
  stage: deploy
  needs: ["test:frontend", "test:backend"]
  script: ./deploy.sh

yaml

stages:
  - build
  - test
  - deploy

build:frontend:
  stage: build
  script: npm run build:frontend

build:backend:
  stage: build
  script: npm run build:backend

test:frontend:
  stage: test
  needs: ["build:frontend"]
  script: npm run test:frontend

test:backend:
  stage: test
  needs: ["build:backend"]
  script: npm run test:backend

deploy:
  stage: deploy
  needs: ["test:frontend", "test:backend"]
  script: ./deploy.sh

Parallel Execution

并行执行

yaml

test:
  parallel:
    matrix:
      - SUITE: [unit, integration, e2e]
  script:
    - npm run test:$SUITE

yaml

test:
  parallel:
    matrix:
      - SUITE: [unit, integration, e2e]
  script:
    - npm run test:$SUITE

Interruptible Jobs

可中断任务

yaml

test:
  interruptible: true
  script:
    - npm test

deploy:production:
  interruptible: false  # Never cancel
  script:
    - ./deploy.sh

yaml

test:
  interruptible: true
  script:
    - npm test

deploy:production:
  interruptible: false  # Never cancel
  script:
    - ./deploy.sh

Configuration Organization

配置组织

Split Configuration Files

拆分配置文件

yaml

undefined

yaml

undefined

.gitlab-ci.yml

include:

local: .gitlab/ci/build.yml
local: .gitlab/ci/test.yml
local: .gitlab/ci/deploy.yml

stages:

build
test
deploy

undefined

include:

local: .gitlab/ci/build.yml
local: .gitlab/ci/test.yml
local: .gitlab/ci/deploy.yml

stages:

build
test
deploy

undefined

Reusable Templates

可复用模板

yaml

.node_template: &node_template
  image: node:20-alpine
  before_script:
    - npm ci
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

test:unit:
  <<: *node_template
  script:
    - npm run test:unit

test:lint:
  <<: *node_template
  script:
    - npm run lint

yaml

.node_template: &node_template
  image: node:20-alpine
  before_script:
    - npm ci
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

test:unit:
  <<: *node_template
  script:
    - npm run test:unit

test:lint:
  <<: *node_template
  script:
    - npm run lint

Extends Keyword

Extends关键字

yaml

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

test:
  extends: .base_job
  script:
    - npm test

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

yaml

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

test:
  extends: .base_job
  script:
    - npm test

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

Resource Management

资源管理

Resource Groups

资源组

yaml

deploy:staging:
  resource_group: staging
  script:
    - ./deploy.sh staging

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

yaml

deploy:staging:
  resource_group: staging
  script:
    - ./deploy.sh staging

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

Runner Tags

Runner标签

yaml

heavy_build:
  tags:
    - high-memory
    - docker
  script:
    - ./build.sh

yaml

heavy_build:
  tags:
    - high-memory
    - docker
  script:
    - ./build.sh

Error Handling

错误处理

Retry Configuration

重试配置

yaml

test:flaky:
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
      - script_failure

yaml

test:flaky:
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
      - script_failure

Allow Failure

允许失败

yaml

test:experimental:
  allow_failure: true
  script:
    - npm run test:experimental

test:experimental:soft:
  allow_failure:
    exit_codes: [42]  # Only allow specific exit code

yaml

test:experimental:
  allow_failure: true
  script:
    - npm run test:experimental

test:experimental:soft:
  allow_failure:
    exit_codes: [42]  # Only allow specific exit code

Security Best Practices

安全最佳实践

Protected Pipelines

受保护流水线

yaml

deploy:production:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
  environment:
    name: production

yaml

deploy:production:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
  environment:
    name: production

Secure Variables

安全变量

yaml

undefined

yaml

undefined

Use protected and masked variables

deploy: script: - echo "$API_KEY" # Masked in logs rules: - if: $CI_COMMIT_REF_PROTECTED == "true"

undefined

deploy: script: - echo "$API_KEY" # Masked in logs rules: - if: $CI_COMMIT_REF_PROTECTED == "true"

undefined

Monitoring & Debugging

监控与调试

Job Logging

任务日志

yaml

test:
  script:
    - set -x  # Enable debug output
    - npm test
  after_script:
    - echo "Job status: $CI_JOB_STATUS"

yaml

test:
  script:
    - set -x  # Enable debug output
    - npm test
  after_script:
    - echo "Job status: $CI_JOB_STATUS"

Pipeline Badges

流水线徽章

markdown

[![Pipeline](https://gitlab.com/group/project/badges/main/pipeline.svg)](https://gitlab.com/group/project/-/pipelines)
[![Coverage](https://gitlab.com/group/project/badges/main/coverage.svg)](https://gitlab.com/group/project/-/pipelines)

markdown

[![Pipeline](https://gitlab.com/group/project/badges/main/pipeline.svg)](https://gitlab.com/group/project/-/pipelines)
[![Coverage](https://gitlab.com/group/project/badges/main/coverage.svg)](https://gitlab.com/group/project/-/pipelines)

Common Anti-Patterns

常见反模式

Avoid: Running all jobs in sequence Do: Use
```
needs
```
for parallel execution
Avoid: Downloading all artifacts Do: Use
```
dependencies
```
to limit downloads
Avoid: Rebuilding node_modules every job Do: Use cache with lock file keys
Avoid: Hardcoded secrets Do: Use CI/CD variables with protection
Avoid: Single monolithic
```
.gitlab-ci.yml
```
Do: Split into multiple included files

避免：按顺序运行所有任务建议：使用
```
needs
```
实现并行执行
避免：下载所有制品建议：使用
```
dependencies
```
限制下载范围
避免：每个任务都重新构建node_modules 建议：结合锁文件关键字使用缓存
避免：硬编码密钥建议：使用带保护的CI/CD变量
避免：单一庞大的
```
.gitlab-ci.yml
```
文件建议：拆分为多个可引入的文件