变量与环境 #

一、变量概述 #

GitLab CI变量用于存储和传递配置信息，支持多种定义方式和优先级。

text

┌─────────────────────────────────────────────────────────────┐
│                    变量优先级（从高到低）                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. 触发变量 (Trigger variables)                             │
│  2. 手动流水线变量 (Manual pipeline variables)               │
│  3. 计划流水线变量 (Scheduled pipeline variables)            │
│  4. Job变量 (Job variables)                                  │
│  5. Stage变量                                                │
│  6. 全局变量 (Global variables)                              │
│  7. 项目变量 (Project variables)                             │
│  8. 组变量 (Group variables)                                 │
│  9. 预定义变量 (Predefined variables)                        │
│                                                              │
└─────────────────────────────────────────────────────────────┘

二、预定义变量 #

项目信息变量 #

变量	说明
`CI_PROJECT_ID`	项目ID
`CI_PROJECT_NAME`	项目名称
`CI_PROJECT_PATH`	项目路径
`CI_PROJECT_URL`	项目URL
`CI_PROJECT_NAMESPACE`	项目命名空间
`CI_PROJECT_VISIBILITY`	项目可见性

提交信息变量 #

变量	说明
`CI_COMMIT_SHA`	完整commit SHA
`CI_COMMIT_SHORT_SHA`	短commit SHA
`CI_COMMIT_MESSAGE`	Commit消息
`CI_COMMIT_BRANCH`	分支名称
`CI_COMMIT_TAG`	标签名称
`CI_COMMIT_REF_NAME`	分支或标签名称
`CI_COMMIT_REF_SLUG`	URL安全的引用名称
`CI_COMMIT_TITLE`	Commit标题
`CI_COMMIT_DESCRIPTION`	Commit描述
`CI_COMMIT_AUTHOR`	Commit作者

流水线信息变量 #

变量	说明
`CI_PIPELINE_ID`	Pipeline ID
`CI_PIPELINE_IID`	Pipeline内部ID
`CI_PIPELINE_SOURCE`	Pipeline触发源
`CI_PIPELINE_TRIGGERED`	是否被触发
`CI_PIPELINE_URL`	Pipeline URL

Job信息变量 #

变量	说明
`CI_JOB_ID`	Job ID
`CI_JOB_NAME`	Job名称
`CI_JOB_STAGE`	Job阶段
`CI_JOB_STATUS`	Job状态
`CI_JOB_URL`	Job URL
`CI_JOB_TOKEN`	Job令牌

Runner信息变量 #

变量	说明
`CI_RUNNER_ID`	Runner ID
`CI_RUNNER_DESCRIPTION`	Runner描述
`CI_RUNNER_TAGS`	Runner标签
`CI_RUNNER_VERSION`	Runner版本

用户信息变量 #

变量	说明
`GITLAB_USER_ID`	用户ID
`GITLAB_USER_LOGIN`	用户登录名
`GITLAB_USER_EMAIL`	用户邮箱
`GITLAB_USER_NAME`	用户名

使用示例 #

yaml

job_name:
  script:
    - echo "Project: $CI_PROJECT_NAME"
    - echo "Branch: $CI_COMMIT_BRANCH"
    - echo "Commit: $CI_COMMIT_SHA"
    - echo "Pipeline: $CI_PIPELINE_ID"
    - echo "Job: $CI_JOB_NAME"
    - echo "User: $GITLAB_USER_LOGIN"

三、自定义变量 #

1. 在.gitlab-ci.yml中定义 #

yaml

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

build:
  script:
    - docker build -t $REGISTRY/$APP_NAME:$CI_COMMIT_SHA .

2. 在GitLab界面定义 #

进入项目Settings → CI/CD
展开Variables部分
点击"Add variable"
填写Key和Value
选择保护选项
保存

3. 项目变量 #

yaml

deploy:
  script:
    - echo "Deploying with token: $DEPLOY_TOKEN"

4. 组变量 #

组变量会继承到所有子项目和项目：

进入组Settings → CI/CD
添加变量

5. Job级别变量 #

yaml

deploy_production:
  variables:
    DEPLOY_ENV: "production"
    DEPLOY_URL: "https://example.com"
  script:
    - echo "Deploying to $DEPLOY_ENV"

四、变量类型 #

1. 普通变量 #

yaml

variables:
  APP_NAME: "myapp"

2. 文件变量 #

文件变量会将值写入临时文件，变量值为文件路径：

yaml

variables:
  SSH_KEY:
    value: "-----BEGIN RSA PRIVATE KEY-----..."
    type: file

deploy:
  script:
    - chmod 600 $SSH_KEY
    - ssh -i $SSH_KEY user@server

3. 环境变量 #

yaml

variables:
  DATABASE_URL: "postgres://user:pass@host:5432/db"

test:
  script:
    - npm test

五、变量保护 #

Protected变量 #

Protected变量只在protected分支和tags上可用：

在添加变量时勾选"Protect variable"
变量只在main、release等protected分支可用

yaml

deploy_production:
  script:
    - echo $PROD_SECRET_KEY
  only:
    - main

Masked变量 #

Masked变量在日志中会被隐藏：

勾选"Mask variable"
变量值必须符合正则表达式要求

yaml

variables:
  SECRET_TOKEN:
    value: "my-secret-token"
    masked: true

六、变量作用域 #

全局变量 #

yaml

variables:
  GLOBAL_VAR: "global_value"

job1:
  script:
    - echo $GLOBAL_VAR

job2:
  script:
    - echo $GLOBAL_VAR

Job变量覆盖全局 #

yaml

variables:
  DEPLOY_ENV: "staging"

deploy_staging:
  variables:
    DEPLOY_ENV: "staging"
  script:
    - echo $DEPLOY_ENV

deploy_production:
  variables:
    DEPLOY_ENV: "production"
  script:
    - echo $DEPLOY_ENV

使用rules动态设置变量 #

yaml

deploy:
  script:
    - echo "Deploying to $DEPLOY_ENV"
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      variables:
        DEPLOY_ENV: "production"
    - if: $CI_COMMIT_BRANCH == "develop"
      variables:
        DEPLOY_ENV: "staging"

七、环境变量 #

定义环境 #

yaml

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

环境变量 #

yaml

deploy_production:
  stage: deploy
  environment:
    name: production
    url: https://example.com
  variables:
    DEPLOY_ENV: production
  script:
    - echo "Deploying to production"

环境作用域变量 #

在Settings → CI/CD → Variables中，可以为特定环境设置变量：

yaml

deploy:
  environment:
    name: production
  script:
    - echo $PROD_DATABASE_URL

环境停止 #

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

八、变量传递 #

传递到下游流水线 #

yaml

trigger_downstream:
  trigger:
    project: my-group/my-project
  variables:
    UPSTREAM_COMMIT: $CI_COMMIT_SHA
    DEPLOY_ENV: staging

继承变量 #

yaml

trigger_child:
  trigger:
    include: child-pipeline.yml
    strategy: depend

子流水线可以访问父流水线的变量。

九、变量最佳实践 #

1. 敏感信息使用Protected变量 #

yaml

deploy_production:
  script:
    - echo $PROD_SECRET_KEY
  only:
    - main

2. 使用变量文件处理多行内容 #

yaml

variables:
  SSH_KEY:
    type: file
    value: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----

3. 使用变量组管理环境配置 #

yaml

.deploy_template:
  variables:
    REGISTRY: registry.example.com
  script:
    - docker push $REGISTRY/$APP_NAME

4. 避免硬编码 #

yaml

variables:
  REGISTRY: registry.example.com
  APP_NAME: myapp

build:
  script:
    - docker build -t $REGISTRY/$APP_NAME:$CI_COMMIT_SHA .

5. 使用变量进行条件判断 #

yaml

deploy:
  script:
    - |
      if [ "$DEPLOY_ENV" == "production" ]; then
        ./deploy-prod.sh
      else
        ./deploy-staging.sh
      fi

十、调试变量 #

打印所有变量 #

yaml

debug_job:
  script:
    - export
    - env

打印特定变量 #

yaml

debug_job:
  script:
    - echo "CI_COMMIT_SHA: $CI_COMMIT_SHA"
    - echo "CI_COMMIT_BRANCH: $CI_COMMIT_BRANCH"
    - echo "CI_PIPELINE_SOURCE: $CI_PIPELINE_SOURCE"

使用CI_DEBUG_TRACE #

yaml

variables:
  CI_DEBUG_TRACE: "true"

job_name:
  script:
    - echo "Hello"

十一、完整示例 #

多环境配置 #

yaml

stages:
  - build
  - deploy

variables:
  REGISTRY: registry.example.com
  APP_NAME: myapp

.build_template:
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $REGISTRY/$APP_NAME:$CI_COMMIT_SHA .
    - docker push $REGISTRY/$APP_NAME:$CI_COMMIT_SHA

build:
  extends: .build_template
  stage: build

deploy_staging:
  stage: deploy
  environment:
    name: staging
    url: https://staging.example.com
  variables:
    DEPLOY_ENV: staging
    KUBE_NAMESPACE: staging
  script:
    - kubectl set image deployment/$APP_NAME $APP_NAME=$REGISTRY/$APP_NAME:$CI_COMMIT_SHA -n $KUBE_NAMESPACE
  only:
    - develop

deploy_production:
  stage: deploy
  environment:
    name: production
    url: https://example.com
  variables:
    DEPLOY_ENV: production
    KUBE_NAMESPACE: production
  script:
    - kubectl set image deployment/$APP_NAME $APP_NAME=$REGISTRY/$APP_NAME:$CI_COMMIT_SHA -n $KUBE_NAMESPACE
  only:
    - main
  when: manual

下一步 #

现在你已经掌握了变量与环境的使用，接下来让我们学习缓存与制品！