写点什么

极狐 GitLab CI/CD 变量黑魔法之自定义变量

作者:极狐GitLab
  • 2023-12-13
    北京
  • 本文字数:3903 字

    阅读完需:约 13 分钟

极狐GitLab CI/CD 变量黑魔法之自定义变量

极狐 GitLab CI/CD 变量是指一系列的环境变量,用来帮助我们控制 CI/CD Job 或 Pipeline 的行为,存储一些可以复用的信息,避免在 .gitlab-ci.yml 中形成硬编码。


极狐 GitLab CI/CD 变量分为预定义变量(predefined CI/CD variables) 和 自定义变量(custom variable) 两部分。今天我们来学习自定义变量这部分。


自定义变量


自定义变量,顾名思义就是需要用户自己定义,先定义,后使用的环境变量。


自定义环境变量有三个级别:


  • 极狐 GitLab 实例级别(这个需要有管理员权限才能使用)

  • 群组(Group)级别

  • 仓库(Project)级别


不同级别的环境变量限制了其使用生效范围,实例级别的环境变量对整个实例下面的所有仓库都有效,群组级别的对整个群组下面的仓库有效,仓库级别的只对此仓库有效。常用的是群组级别和仓库级别的。下面分别介绍并进行演示。


群组(Group)级别


首先,创建一个群组(Group)级别的环境变量:Group --> Settings --> CI/CD --> Variables --> Add variable,写入对应的 key 和 value 即可,如下图



上述操作创建了一个 key 为 GROUP_VARS,value 为 JiHu-GitLab 的群组(Group)级别的环境变量。


在当前群组(Group)的任意一个仓库(Project)下面用极狐 GitLab CI 功能测试一下,将下述内容写入 .gitlab-ci.yml 文件


image: busybox:latest
stages: - test
build: stage: test script: - echo "Group Variable is GROUP_VARS and value is $GROUP_VARS"
复制代码


触发 CI/CD Pipeline 之后,查看构建结果



可以看到 GROUP_VARS 在群组(Group)的 CI/CD 环境变量中定义了,所以会输出正常的值,如果环境变量没有定义,会出现什么结果呢?


将下述内容写入 .gitlab-ci.yml 文件


image: busybox:latest
stages: - test
build: stage: test script: - echo "Group Variable is GROUP_VARS and value is $GROUP_VARS" - echo "Group Variable is NON_GROUP_VARS and value is $NON_GROUP_VARS"
复制代码


其中 GROUP_VARS 是提前定义了的环境变量,而 NON_GROUP_VARS 是没有经过定义的环境变量。


触发 CI/CD Pipeline 之后,查看构建结果



可以看到 NON_GROUP_VARS 没有提前定义,而且也不是预定义变量,所以值为空。


上述 Demo 是在定义群组(Group)环境变量的群组(Group)内的任意仓库中实现的.说明群组(Group)级别的自定义环境变量对当前群组下面的所有仓库(Project)均有效。


仓库(Project)级别


仓库(Project)级别的环境变量有三种创建方式


  • 通过仓库(Project)内的 .gitlab-ci.yml 文件

  • 通过仓库(Project)的 Settings,这个和群组(Group)的创建类似

  • 通过 API 来创建


下面分别展示三种情况下的自定义环境变量的定义和使用。


使用 .gitlab-ci.yml 创建


在 .gitlab-ci.yml 文件中使用自定义变量,需要通过关键字 variables 先定义环境变量。variables 关键字可以出现在 .gitlab-ci.yml 文件内容的最顶端,这种情况下,自定义变量对当前整个 Pipeline 全局有效,也即意味着所有 Stage,Job 均可以使用;variables 关键字也可以出现在单个 Job 中,此时,自定义环境变量只对当前 Job 有效。测试如下:


variables:  PROJECT_TEST_VAR: "project_global_var"
image: busybox:latest
stages: - test - test1
job: stage: test variables: JOB_TEST_VAR: "job_test_var" script: - echo "Global Project Variable is PROJECT_TEST_VAR and value is $PROJECT_TEST_VAR" - echo "Job Variable is JOB_TEST_VAR and value is $JOB_TEST_VAR"
job1: stage: test script: - echo "Global Project Variable is PROJECT_TEST_VAR and value is $PROJECT_TEST_VAR" - echo "Job Variable is JOB_TEST_VAR and value is $JOB_TEST_VAR"
复制代码


上述代码定义了一个全局的自定义环境变量:PROJECT_TEST_VAR,值为 project_global_var;定义了一个 Job 级别的环境变量:JOB_TEST_VAR,值为 job_test_var。job 的输出如下



可以看到:全局环境变量 PROJECT_TEST_VAR 在 job 中可见可用;job 级别的环境变量 JOB_TEST_VAR 仅在 job 中可见可用,因为是在 job 中定义的。

job1 的输出如下



可以看到:全局环境变量 PROJECT_TEST_VAR 在 job1 中可见可用,job 级别的环境变量 JOB_TEST_VAR 在 job1 中不可见不可用,因为是在 job 中定义的,生效范围仅仅是 job 级别的。


结论:全局的环境变量对于所有 job 可见可用,但是 job 级别的环境变量只对当前 job 可用可见,在其他 job 是不可见不可用的。


通过仓库的 Settings 创建


这一点和前面群组(Group)的使用一样,先创建变量:Project --> Settings --> CI/CD --> Variables --> Add Variable,添加 key 为 PROJECT_VARS,value 为 JiHu-GitLab-Project 的环境变量。使用下述代码进行测试:


image: busybox:latest
stages: - test
job: stage: test variables: JOB_TEST_VAR: "job_test_var" script: - echo "Project Variable is PROJECT_VARS and value is $PROJECT_VARS"
job1: stage: test script: - echo "Project Variable is PROJECT_VARS and value is $PROJECT_VARS"
复制代码


查看构建结果



可以看到两个 job 的输出结果是一样。


结论:通过仓库(Project) Settings 创建的环境变量对当前仓库(Project)中所有 Pipeline 所包含的 job 均可见可用。


通过 API 创建


极狐 GitLab 提供丰富的 API 用来对环境变量的增、删、改、查进行操作。创建变量的 API 方法如下:


curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \     "https://gitlab.cn/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value"
复制代码


指定极狐 GitLab token 及极狐 GitLab 地址:https://gitlab.cn,然后将需要创建的变量以 --form 的形式传入,执行上述命令后,得到如下返回信息


{  "variable_type":"env_var",  "key":"xiaomage",  "value":"Evangelist",  "protected":false,  "masked":false,  "environment_scope":"*"}
复制代码


上述信息表明 key 为 xiaomage,value 为 Evangelist 的变量已经创建成功。可以用下面的 API 继续查看当前仓库(Project)里面的现有环境变量


[  {    "variable_type":"env_var",    "key":"PROJECT_VARS",    "value":"JiHu-GitLab-Project",    "protected":false,    "masked":false,    "environment_scope":"*"  },  {    "variable_type":"env_var",    "key":"xiaomage",    "value":"Evangelist",    "protected":false,    "masked":false,    "environment_scope":"*"  }]
复制代码


可以看到当前仓库(Project)有两个变量 PROJECT_VARS、xiaomage。其中 PROJECT_VARS 是通过仓库(Project)Settings 创建的。而 xiaomage 就是用上述 API 创建的。


在仓库(Project)的 CI/CD Variables 下面也可以看到名为 xiaomage 的变量。



大招时刻


相信大家也看到了,极狐 GitLab 的环境变量定义手段非常丰富,当然使用也就非常灵活了。下面讲几种大家关心而且常用的环境变量使用小魔法。


变量的覆盖(Override)


自定义的变量是可以在 Pipeline 运行的时候被覆盖的,诸如上述名为 xiaomage,值为 Evangelist 的环境变量。可以在手动运行 Pipeline 的时候覆盖其原来的值。


方法为:Project --> Pipelines --> Run Pipeline,在出现的界面中,修改环境变量的值



然后点击 Run Pipeline,查看构建结果



可以看到值已经从 Evangelist 变成了 JiHu-Evangelist 了 。


变量的遮掩(Mask)


经过遮掩(Mask)的变量,其值在 Pipeline logs 中是不会显示的,这种方法对于将敏感信息存储为环境变量的场景比较常用。如果敏感信息在 Pipeline log 中输出,很容易造成敏感信息的泄漏。


遮掩(Mask)一个变量的方法很简单:仓库(Project) --> CI/CD --> Variables --> Add variable,在出现的选项中勾选 Mask variable



在 Pipeline 的构建 log 中,可以看到值显示 MASKED,而不是真实的值。



变量的传递


DevOps Pipeline 中经常遇到的一个问题就是,变量在不同 Job 间的传递。其实上面极狐 GitLab CI/CD 变量的不同定义方法就能满足变量在不同 Job 间的使用。但是极狐 GitLab 还有一种能够完成环境变量在不同 Job 间的传递。使用方法如下:


  • 在前面的 Job 中,将环境变量存储在 .env 文件中

  • 用 artifacts:reports:dotenv 关键字将 .env 文件标记为制品

  • 在后续的 Job 中使用关键字 dependencies 或 needs 来使用传递过来的环境变量。


测试代码如下


image: busybox:latest
stages: - build - deploy
build: stage: build script: - echo "NAME=xiaomage" >> build.env - echo "TITLE=JiHu-Evangelist" >> build.env artifacts: reports: dotenv: build.env
deploy: stage: deploy script: - echo "$NAME" - echo "$TITLE" dependencies:
复制代码


可以查看构建结果



当然,也可以用使用 needs 关键字来完成变量的传递


image: busybox:latest
stages: - build - deploy
build: stage: build script: - echo "NAME=xiaomage" >> build.env - echo "TITLE=JiHu-Evangelist" >> build.env artifacts: reports: dotenv: build.env
deploy: stage: deploy script: - echo "$NAME" - echo "$TITLE" needs: - job: build artifacts: true
复制代码


构建结果是一样的



写在最后


极狐 GitLab CI/CD 中对于环境变量的定义、使用都是非常灵活的,功能非常强大,而且每个迭代的版本都有新功能推出。能满足多种场景下的 CI/CD Pipeline 构建。欢迎大家体验、使用!

发布于: 刚刚阅读数: 5
用户头像

极狐GitLab

关注

开源开放,人人贡献 2021-05-19 加入

开放式一体化DevOps平台,助力行业高速协同增长!

评论

发布
暂无评论
极狐GitLab CI/CD 变量黑魔法之自定义变量_DevOps_极狐GitLab_InfoQ写作社区