CNB TCA 插件

支持在云原生构建（Cloud Native Build，CNB）中触发代码分析，提供快速分析、深度分析模式。

一、快速分析

提示

快速分析使用默认的代码安全分析规则，无需配置分析方案，开箱即用。

使用指引

将以下内容复制到 .cnb.yml 文件中，即可在 CNB 中触发快速分析。

# .cnb.yml
"**":  # 触发的分支名，默认所有分支，可按需修改
  push:  # push 触发，可按需修改为 pull_request 等
    - stages:
      # 获取 git 变更文件列表，供 TCA 增量分析使用
      - name: git-change-list
        image: cnbcool/git-change-list:latest
        settings:
          changed: changed.txt  # 将变更文件列表输出到txt文件中，供后续TCA使用
      # 代码分析
      - name: TCA
        image: tencentcom/tca-plugin:latest
        settings:
          from_file: changed.txt  # 默认只分析 git 变更文件，如果希望分析全量代码，可注释掉该参数
          block: true  # 如果有代码问题或分析异常，会阻塞流水线。如果不希望阻塞流水线，可以设置为false。
          smtp_username:   # 可选，邮件报告 - 发件人邮箱地址，建议使用QQ邮箱
          smtp_auth_code:  # 可选，邮件报告 - 邮件服务器的授权码，建议使用QQ邮箱授权码
          receiver_email:  # 可选，邮件报告 - 收件人邮箱地址

参数说明

提示

以下参数仅适用于快速分析场景。

核心参数说明

参数	类型	必填项	默认值	参数描述
block	bool	否	true	存在代码问题或分析异常是否阻塞流水线
comment	bool	否	true	是否将代码分析结果添加到 `pull_request` 评论
ignore_paths	str list	否		忽略路径（Unix 通配符格式），指定一个或多个相对工作区的屏蔽路径，多个路径采用数组格式填写： 1.匹配src/test目录：`src/test/` 2.匹配根目录下的test目录：`test/` 3.匹配所有_test.py后缀的文件：`*_test.py`
white_paths	str list	否		分析路径（Unix 通配符格式），指定一个或多个相对工作区的分析路径，多个路径采用数组格式填写

邮件参数说明

如需发送邮件报告，需要配置以下参数：

参数	类型	必填项	默认值	参数描述
smtp_username	str	是		邮件服务器的登录名（即发件人邮箱地址，建议使用 QQ 邮箱）
smtp_auth_code	str	是		邮件服务器的授权码，如不希望暴露授权码，可配置在密钥仓库后通过 `settingsFrom` 引用
receiver_email	str list	是		收件人邮箱地址，多个采用数组格式填写，可以不限于 QQ 邮箱
smtp_host	str	否	smtp.qq.com	邮件服务器地址
smtp_port	int	否	465	邮件服务器端口
cc_receiver_email	str list	否		抄送人邮箱地址，多个采用数组格式填写

查看结果

分析报告

分析完成后，会在日志内打印出所有问题列表。
分析完成后，会在当前工作空间的 tca_report 目录下输出 JSON 和 HTML 报告，可供下游步骤使用：
- JSON 报告：tca_report/tca_report.json
- HTML 报告：tca_report/tca_report.html

邮件报告

分析结果可发送到个人邮箱，可参考上述邮件参数说明，完成邮件配置。

提示

如何获取QQ邮箱授权码：请点击查阅。

合并请求评论

pull_request 触发的代码分析结果，会自动添加到合并请求评论。

二、深度分析

提示

深度分析支持自定义分析方案、质量门禁指标，持续跟踪代码问题等。
深度分析需要与 TCA 平台通信
- 可通过配置 mode 参数指定 远端分析模式 node、本地分析模式 local。
- 默认 node 模式，使用远端节点执行代码分析，即分析任务会由 TCA 平台下发到对应的在线节点上执行。
- 可通过配置 mode 参数为 local，即切换成本地分析模式（数据和报告也直接产出在当地，可自由使用）。

使用指引

先在 TCA 上创建好 团队 和 项目（如果已有，可忽略），接入 CNB 代码仓库，按需求配置分析方案，创建分析项目。可参考快速开始。
接入仓库后，进入代码库页面，并点击 插件配置，进入 TCA 插件配置弹框页，并选择 CNB 云原生构建 页签。
提示
- 密钥文件地址参见第 3、4、5 步骤，如果已存在该地址，可以跳过对应步骤，直接输入到密钥文件地址输入框即可！
- 插件所需的凭证信息为个人敏感信息，请注意保密！
在 cnb.cool 上创建一个新的代码仓库（仓库类型选择 密钥仓库，密钥仓库是仅允许页面查看和修改，适用于云原生构建加载密钥的仓库），比如：tca-private-config。
在密钥仓库中创建一个 yaml 文件，比如 tca-settings.yml，将第 2 步插件配置截图中的凭证信息拷贝到该文件中，并提交即可。点击了解文件引用文档。
复制该密钥文件 URL 地址，粘贴到第 2 步插件配置截图中的 密钥文件地址 输入框中，URL示例：https://cnb.cool/xxx/tca-private-config/-/blob/main/tca-settings.yml。
在 CNB 云原生构建 页签选择需要使用的分析方案，如果没有，需要先创建，可参考分析方案。
点击 生成 .cnb.yml TCA 插件配置 按钮，进入 cnb.cool 对应的仓库根目录下，将生成的配置内容复制到 .cnb.yml 中（如果不存在，需要先创建 .cnb.yml 文件，点击了解更多）。

仅为示例，请从 TCA 官网代码库页面插件配置中自动生成。

# .cnb.yml
"**":  # 触发的分支名，默认所有分支，可按需修改
  push:  # push触发，也可以用 pull_request 等触发
    - docker:
        # 声明缓存目录，/data/tca_cache/tools 为TCA 插件工具存储目录
        volumes:
          - /data/tca_cache/tools:copy-on-write
      stages:
        # 代码分析
        - name: TCA
          image: tencentcom/tca-plugin:latest
          settings:
            mode: local  # 执行模式，可选值：local（本地分析模式），node(远端节点分析模式)， 默认值：node
            org_sid: xxx  # 团队编号（请从TCA官网生成配置，无需自行添加）
            team_name: xxx  # 项目名称（请从TCA官网生成配置，无需自行添加）
            scheme_id: xxx  # 分析方案id（请从TCA官网生成配置，无需自行添加）
          settingsFrom:
            # 密钥文件引用。请检查使用此配置的代码库是否具有访问密钥文件的权限，否则会导致构建失败！
            - https://cnb.cool/xxx/tca-private-config/-/blob/main/tca-settings.yml

参数说明

提示

以下参数仅适用于深度分析场景。优先级高于在 TCA 平台配置的参数。
可点击查看 TCA 插件，查看插件全文，以及相关参数等。

核心参数说明

参数	类型	必填项	默认值	参数描述
org_sid	str	是		团队唯一标识，从 TCA 平台获取
team_name	str	是		项目唯一标识，从 TCA 平台获取
scheme_id	str	是		分析方案 ID，从 TCA 平台获取
mode	str	否	node	分析模式，可选值：`local`（本地分析模式）、`node`（远端节点分析模式）
total_scan	bool	否	false	是否全量分析，true 为全量分析，false 为增量分析
block	bool	否	true	存在质量门禁不通过或分析异常是否阻塞流水线
comment	bool	否	true	是否将代码分析结果添加到 `pull_request` 评论
scan_dir	str	否		分析目录，默认为待分析代码仓库根目录，可填写目录的相对路径，指定代码仓库下的子目录作为分析目录
ignore_paths	str list	否		忽略路径（Unix 通配符格式），指定一个或多个相对工作区的屏蔽路径，多个路径采用数组格式填写： 1.匹配src/test目录：`src/test/` 2.匹配根目录下的test目录：`test/` 3.匹配所有_test.py后缀的文件：`*_test.py`
white_paths	str list	否		分析路径（Unix 通配符格式），指定一个或多个相对工作区的分析路径，多个路径采用数组格式填写
pre_cmd	str 或 list	否		前置命令，适用于编译型分析工具，与编译命令配合使用，在编译命令之前、当前工作空间目录下执行，多个前置命令采用数组格式填写
build_cmd	str	否		编译命令，适用于编译型分析工具，在当前工作空间目录下执行

对比分支参数说明

参数	类型	必填项	默认值	参数描述
compare_branch	str	否		对比分支，只分析当前分支相对于对比分支的增量问题

提示

合并请求触发（MR/PR 触发），此参数配置值会被忽略，会自动获取目标分支作为对比分支。

由于 push 触发，CNB 只会 checkout 当前分支，本地无法获取到对比分支信息，会影响增量对比分析，因此需要在 TCA 插件前通过 git fetch 命令先拉取对比分支。以下是设置 compare_branch 为 main 分支的例子：

# .cnb.yml
feat/dev:  # 触发的分支名，请修改为实际的分支名
  push:  # push触发
    - docker:
        # 声明缓存目录，/data/tca_cache/tools 为TCA 插件工具存储目录
        volumes:
          - /data/tca_cache/tools:copy-on-write
      stages:
        # 拉取对比分支
        - name: fetch compare branch
          script: git fetch origin main  # 请将 main 修改为实际的对比分支名
        # 代码分析
        - name: TCA
          image: tencentcom/tca-plugin:latest
          settings:
            mode: local
            compare_branch: main  # 对比分支名，请修改为实际的对比分支名
            org_sid: xxx  # 团队编号，从TCA官网获取
            team_name: xxx  # 项目名称，从TCA官网获取
            scheme_id: xxx  # 分析方案id，从TCA官网获取
            total_warning: 0       # 质量门禁，项目存量（严重+错误+警告）问题量小于等于0
          settingsFrom:
            - https://cnb.cool/xxx/tca-private-config/-/blob/main/tca-settings.yml

质量门禁参数说明

提示

仅针对 mode: local，即仅本地分析模式生效！
搭配 block: true 参数，质量门禁不通过则阻塞流水线。
远端分析模式下请在 TCA 平台 分析方案 - 质量门禁 页面完成门禁指标配置。

参数	类型	必填项	参数描述
total_fatal	number	否	严重问题指标（问题量：严重），需开启代码检查，整数，推荐值：0
total_error	number	否	错误问题指标（问题量：严重 + 错误），需开启代码检查，整数，推荐值：0
total_warning	number	否	警告问题指标（问题量：严重 + 错误 + 警告），需开启代码检查，整数，推荐值：0
total_info	number	否	提示问题指标（问题量：严重 + 错误 + 警告 + 提示），需开启代码检查，整数，推荐值：0
worse_cc_file_num	number	否	圈复杂度恶化文件数，需开启圈复杂度，整数，推荐值：0
duplicate_rate	number	否	代码重复率，需开启重复代码，整数，推荐值：3