.gitlab-ci.yml #

一、文件结构 #

基本结构 #

yaml 
stages:
  - stage1
  - stage2

variables:
  VAR1: "value1"

before_script:
  - echo "Global before script"

after_script:
  - echo "Global after script"

cache:
  paths:
    - node_modules/

job1:
  stage: stage1
  script:
    - echo "Job 1"

job2:
  stage: stage2
  script:
    - echo "Job 2"

结构说明 #

关键字 说明
stages 定义Pipeline的阶段顺序
variables 定义全局变量
before_script 所有Job执行前运行的命令
after_script 所有Job执行后运行的命令
cache 定义缓存策略
job_name 定义具体的作业

二、全局关键字 #

1. stages（阶段） #

定义Pipeline的执行顺序：

yaml 
stages:
  - build
  - test
  - deploy

默认阶段：

yaml 
stages:
  - build
  - test
  - deploy

2. variables（变量） #

定义全局变量：

yaml 
variables:
  APP_NAME: "myapp"
  REGISTRY: "registry.example.com"
  NODE_ENV: "production"

3. default（默认配置） #

为所有Job设置默认值：

yaml 
default:
  image: node:18
  before_script:
    - npm install
  cache:
    paths:
      - node_modules/
  retry:
    max: 2

4. workflow（工作流） #

控制Pipeline的创建：

yaml 
workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: always
    - if: $CI_COMMIT_BRANCH == "develop"
      when: always
    - when: never

5. include（包含） #

引入外部配置文件：

yaml 
include:
  - local: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-project'
    ref: main
    file: '/templates/.gitlab-ci-template.yml'
  - remote: 'https://example.com/.gitlab-ci-template.yml'
  - template: 'Auto-DevOps.gitlab-ci.yml'

三、Job关键字 #

1. script（脚本） #

定义Job执行的命令：

yaml 
job_name:
  script:
    - echo "Hello"
    - npm test

单行简写：

yaml 
job_name:
  script: echo "Hello"

2. stage（阶段） #

指定Job所属的阶段：

yaml 
test_job:
  stage: test
  script:
    - npm test

3. image（镜像） #

指定使用的Docker镜像：

yaml 
job_name:
  image: node:18
  script:
    - npm test

详细配置：

yaml 
job_name:
  image:
    name: node:18
    entrypoint: ["/bin/bash"]
  script:
    - npm test

4. services（服务） #

启动额外的服务容器：

yaml 
test_job:
  image: node:18
  services:
    - postgres:14
    - redis:7
  variables:
    POSTGRES_DB: test
    POSTGRES_USER: test
    POSTGRES_PASSWORD: test
  script:
    - npm test

详细配置：

yaml 
test_job:
  services:
    - name: postgres:14
      alias: db
      variables:
        POSTGRES_DB: test

5. variables（Job变量） #

定义Job级别变量：

yaml 
deploy_job:
  variables:
    ENVIRONMENT: "production"
    DEPLOY_URL: "https://example.com"
  script:
    - echo "Deploying to $ENVIRONMENT"

6. cache（缓存） #

缓存文件和目录：

yaml 
job_name:
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
      - .npm/
    policy: pull-push

缓存策略：

策略 说明
pull-push 拉取并更新缓存（默认）
pull 只拉取缓存
push 只更新缓存

7. artifacts（制品） #

保存Job的产物：

yaml 
build_job:
  script:
    - npm run build
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - dist/
      - build/
    exclude:
      - dist/*.log
    expire_in: 1 week
    when: always

8. dependencies（依赖） #

指定依赖的Job：

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

test:
  stage: test
  dependencies:
    - build
  script:
    - ls dist/

9. needs（需求） #

定义Job依赖关系，实现DAG执行：

yaml 
lint:
  stage: test
  script: npm run lint

test_unit:
  stage: test
  script: npm run test:unit

test_integration:
  stage: test
  needs: [lint]
  script: npm run test:integration

deploy:
  stage: deploy
  needs: [test_unit, test_integration]
  script: echo "Deploying..."

10. environment（环境） #

定义部署环境：

yaml 
deploy_staging:
  stage: deploy
  environment:
    name: staging
    url: https://staging.example.com
    on_stop: stop_staging
  script:
    - echo "Deploying to staging"

stop_staging:
  stage: deploy
  environment:
    name: staging
    action: stop
  script:
    - echo "Stopping staging"
  when: manual

11. extends（继承） #

继承配置：

yaml 
.deploy_template:
  script:
    - echo "Deploying..."
  only:
    - main

deploy_staging:
  extends: .deploy_template
  environment: staging

deploy_production:
  extends: .deploy_template
  environment: production

12. trigger（触发） #

触发下游Pipeline：

yaml 
trigger_pipeline:
  stage: deploy
  trigger:
    project: my-group/my-project
    branch: main
    strategy: depend

四、执行控制 #

1. only/except（简单条件） #

yaml 
job_name:
  script: echo "Hello"
  only:
    - main
    - tags
    - /^release-.*$/
  except:
    - branches

2. rules（复杂条件） #

yaml 
job_name:
  script: echo "Hello"
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: always
    - if: $CI_COMMIT_BRANCH == "develop"
      when: manual
    - when: never

3. when（执行时机） #

yaml 
job_name:
  script: echo "Hello"
  when: manual
值 说明
on_success 前面Job成功时执行（默认）
on_failure 前面Job失败时执行
always 总是执行
manual 手动执行
delayed 延迟执行

4. allow_failure（允许失败） #

yaml 
job_name:
  script: npm run lint
  allow_failure: true

详细配置：

yaml 
job_name:
  script: npm run lint
  allow_failure:
    exit_codes:
      - 137
      - 255

5. retry（重试） #

yaml 
job_name:
  script: npm test
  retry:
    max: 2
    when:
      - script_failure
      - runner_system_failure

6. timeout（超时） #

yaml 
job_name:
  script: ./long-script.sh
  timeout: 3h

7. interruptible（可中断） #

yaml 
job_name:
  script: npm test
  interruptible: true

五、资源控制 #

1. tags（标签） #

指定Runner标签：

yaml 
job_name:
  tags:
    - docker
    - linux
  script:
    - echo "Running on tagged runner"

2. resource_group（资源组） #

控制并发：

yaml 
deploy_job:
  stage: deploy
  resource_group: production
  script:
    - echo "Deploying..."

3. parallel（并行） #

并行执行：

yaml 
test_job:
  parallel: 5
  script:
    - echo "Running test $CI_NODE_INDEX of $CI_NODE_TOTAL"

矩阵并行：

yaml 
test_job:
  parallel:
    matrix:
      - NODE_VERSION: [16, 18, 20]
        OS: [linux, windows]
  image: node:${NODE_VERSION}
  script:
    - echo "Testing Node $NODE_VERSION on $OS"

六、脚本关键字 #

1. before_script #

Job执行前运行：

yaml 
job_name:
  before_script:
    - echo "Preparing..."
    - npm install
  script:
    - npm test

2. after_script #

Job执行后运行（即使失败）：

yaml 
job_name:
  script:
    - npm test
  after_script:
    - echo "Cleaning up..."

七、完整示例 #

Node.js项目 #

yaml 
stages:
  - install
  - test
  - build
  - deploy

variables:
  NODE_VERSION: "18"

.node_template:
  image: node:${NODE_VERSION}
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

install:
  extends: .node_template
  stage: install
  script:
    - npm ci
  artifacts:
    paths:
      - node_modules/

lint:
  extends: .node_template
  stage: test
  dependencies:
    - install
  script:
    - npm run lint
  allow_failure: true

test:
  extends: .node_template
  stage: test
  dependencies:
    - install
  script:
    - npm test
  coverage: '/Coverage: \d+%/'

build:
  extends: .node_template
  stage: build
  dependencies:
    - install
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

deploy_staging:
  stage: deploy
  environment:
    name: staging
    url: https://staging.example.com
  script:
    - echo "Deploying to staging..."
  only:
    - develop

deploy_production:
  stage: deploy
  environment:
    name: production
    url: https://example.com
  script:
    - echo "Deploying to production..."
  only:
    - main
  when: manual

Docker项目 #

yaml 
stages:
  - build
  - test
  - deploy

variables:
  DOCKER_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

docker_build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build -t $DOCKER_IMAGE .
    - docker push $DOCKER_IMAGE

docker_test:
  stage: test
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker run $DOCKER_IMAGE npm test

deploy:
  stage: deploy
  image: bitnami/kubectl:latest
  script:
    - kubectl set image deployment/myapp myapp=$DOCKER_IMAGE
  only:
    - main

八、YAML语法技巧 #

1. 锚点和别名 #

yaml 
.node_template: &node_template
  image: node:18
  before_script:
    - npm install

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

build:
  <<: *node_template
  script:
    - npm run build

2. 多行字符串 #

yaml 
job_name:
  script:
    - |
      echo "This is a
      multi-line
      script"

3. 条件表达式 #

yaml 
job_name:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      variables:
        DEPLOY_ENV: "production"
    - if: $CI_COMMIT_BRANCH == "develop"
      variables:
        DEPLOY_ENV: "staging"

下一步 #

现在你已经了解了.gitlab-ci.yml的详细配置，接下来让我们学习 作业与阶段！

最后更新：2026-03-28