1.让GitLab CI/CD做什么

嵌入式软件开发领域高频使用的开发语言是C语言，在大型项目开发中，我们往往会有格式审查、编译审查的需求。如果能借助GitLab平台实现代码的格式和编译问题审查，将会极大提高合入代码的规范性，把控新代码对原有代码的影响，提高代码整体质量。

本文将手把手教学如何借助CI帮我们做代码格式审查、编译审查。

2.GitLab CI/CD快速搭建

2.1 VC Code设置

1. 将VS Code设置为保存时自动格式化。

2. 在代码根目录下放置.clang-format和.clang-format-ignore文件。

.clang-format文件是代码格式化和格式检查的配置文件，可以从Clang-Format官方网页下载到模板再根据自己的需求调整，语法详见链接。编辑好了.clang-format这个文件，置于代码根目录，用VS Code编辑完代码后执行保存操作，保存的文件将自动按这个文件的格式规范来格式化代码。

.clang-format-ignore文件是用于配置在CI中忽略代码格式检查的文件或文件夹。

2.2 GitLab 配置

前提：你已经在GitLab有代码仓库，并且你是仓库的Owner或Maintainer身份。

如何让GitLab CI/CD为我们做代码格式的审查和编译审查呢，总结起来就五点：

1. 仓库根目录配置.gitlab-ci.yml文件；
2. 仓库中配置代码审查的脚本、clang-format格式审查工具和编译脚本；
3. 配置一个用于编译的MDK工程；
4. 为GitLab公共仓库配置一个Runner（一般是服务器）；
5. 为GitLab个人仓库配置一个Runner（一般是本机）；
6. Runner环境配置。

.gitlab-ci.yml可以理解为流水线文件，使用 YAML语法描述，.gitlab-ci.yml文件描述了你要做什么事情。本需求包括代码的拉取、代码格式审查和代码编译。把.gitlab-ci.yml放到远端分支的根目录，你每次push或Merge代码到Git远程仓库时，Runner都会自动触发CI pipeline，去执行.gitlab-ci.yml流水线文件中描述的事。

Runner很好理解，就是一个用来跑仓库代码的格式审查与编译审查的机器，一般公共仓库会是一台服务器，个人仓库会是本机。

3.具体配置流程

3.1 .gitlab-ci.yml文件

.gitlab-ci.yml如下：

文件描述了代码更新方式和两个Job。一个Job是check，做代码格式审查；另一个Job是build，做代码编译。script描述的是执行命令，即在Runner中执行的命令。tags描述的是Runner的标识，与Runner注册时的设置一致，用于在CI pipeline中顺利找到该主机。

代码格式审查的命令：python .workflow/ci/format_check/run-clang-format.py --clang-format-executable .workflow/ci/format_check/clang-format.exe -r components/ 。命令中调用了Python脚本和clang-format.exe执行文件，并指定了要检查的文件夹路径。

代码编译的命令：.workflow/ci/build/build_keil.bat，调用了指定路径下的编译脚本。

3.2 脚本及工具配置

在代码仓库.workflow > ci路径下的不同文件夹中放置格式审查的脚本、clang-format格式审查工具、编译脚本：

format_check文件夹放置run-clang-format.py格式审查脚本和clang-format.exe执行文件，clang-format.exe版本为12.0.1：

build文件夹放置build_keil.bat编译脚本：

3.3 编译工程

在代码仓库.workflow > ci > projects_compile路径下放置一个或多个用于编译的MDK工程，通过一个或多个工程的配置来铺盖所有代码。

3.4 公共仓库配置Runner

首先需要找到一台windows主机。

1. 在系统中的某处创建一个文件夹，例如：F:\OneOS_Operate_System\GitLab-Runner。

2. 下载64 位或32 位二进制文件并将其放入创建的文件夹中。重命名为gitlab-runner.exe（可选）。

3. 注册Runner

   打开Windows PowerShell，进入F:\OneOS_Operate_System\GitLab-Runner路径运行./gitlab-runner.exe register命令：中间阶段需要输入URL、Token、Runner的描述、Runner的标识、shell。其中Runner的标识需要与.gitlab-ci.yml文件中的tags描述的Runner的标识一致，否则无法找到指定的Runner。

   

   其中的URL和Token则是来自代码仓库的Runner设置中：

   

4. 修改config.toml

   注册完Runner后，可以在F:\OneOS_Operate_System\GitLab-Runner文件夹下看到config.toml文件，打开并修改一处：shell = "pwsh"为shell = "powershell"

5. 启动Runner

   继续在Windows PowerShell中依次执行命令.\gitlab-runner.exe install和.\gitlab-runner.exe start就可以启动Runner：

   

   启动成功后可以看到Runner下多了一个设备，设备标识为win_ci，因此.gitlab-ci.yml文件中的tags也应该是win_ci：

   

3.5 个人仓库配置Runner

个人仓库的Runner搭建在本机，配置方法基本等同于公共仓库的Runner配置方法，唯一差别是注册Runner时的URL、Token需要从个人仓库的中获取。注册时输入的Runner标识与公共仓库的Runner标识保持一致。

3.6 Runner环境配置

要想让Runner成功的跑格式审查命令：python .workflow/ci/format_check/run-clang-format.py --clang-format-executable .workflow/ci/format_check/clang-format.exe -r components/ 和代码编译的命令：.workflow/ci/build/build_keil.bat还需要对Runner做一定的配置（服务器和本机都必须要）：

1. 安装python

2. 安装MDK v5

3. 添加系统环境变量（Python和MDK都要确保添加）

   

3.7 重启Runner

输入命令：./gitlab-runner.exe restart来重启Runner，首次服务器和本机都要执行此命令重启Runner。成功后就不用在执行此命令，主机即使重启也可以正常使用Runner不需要做其它。

3.8 触发

个人仓库的push或从个人仓库向公共仓库提Merge请求会触发流水线，会对整个代码仓库进行代码格式审查和编译，任何一项不通过将无法合入公共仓库。

4. 关注&&联系

gitee： https://gitee.com/cmcc-oneos/OneOS-Lite

docs： https://oneos-lite.com/