CNB TCA Plugin

Supports triggering code analysis within Cloud Native Build (CNB), providing fast analysis and deep analysis modes.

I. Fast Analysis

Tips

Fast analysis uses default code security analysis rules, requires no analysis scheme configuration, and is ready to use out of the box.

Usage Guide

Copy the following content into the .cnb.yml file to trigger fast analysis in CNB.

# .cnb.yml
"**":  # Triggered branch names, default to all branches, can be modified as needed
  push:  # Triggered by push, can be modified to pull_request, etc.
    - stages:
      # Get the list of changed git files for TCA incremental analysis
      - name: git-change-list
        image: cnbcool/git-change-list:latest
        settings:
          changed: changed.txt  # Output the list of changed files to a txt file for subsequent TCA use
      # Code analysis
      - name: TCA
        image: tencentcom/tca-plugin:latest
        settings:
          from_file: changed.txt  # By default, only analyze git changed files; comment out this parameter to analyze all code
          block: true  # Blocks the pipeline if there are code issues or analysis exceptions. Set to false if pipeline blocking is not desired.
          smtp_username:   # Optional, email report - sender email address, QQ email recommended
          smtp_auth_code:  # Optional, email report - mail server authorization code, QQ email authorization code recommended
          receiver_email:  # Optional, email report - recipient email address

Parameter Description

Tips

The following parameters apply only to the fast analysis scenario.

Core Parameters

ParameterTypeRequiredDefault ValueDescription
blockboolNotrueWhether to block the pipeline if there are code issues or analysis exceptions
commentboolNotrueWhether to add code analysis results to pull_request comments
ignore_pathsstr
list		No-Paths to ignore (Unix wildcard format), specify one or more relative workspace paths to exclude. Multiple paths use array format:
1. Match src/test directory: src/test/*
2. Match test directory under root: test/*
3. Match all files ending with _test.py: *_test.py
white_pathsstr
list		No-Paths to analyze (Unix wildcard format), specify one or more relative workspace paths to include. Multiple paths use array format

Email Parameters

To send email reports, configure the following parameters:

ParameterTypeRequiredDefault ValueDescription
smtp_usernamestrYes-Mail server login name (i.e., sender email address, QQ email recommended)
smtp_auth_codestrYes-Mail server authorization code. To avoid exposing the code, configure it in a secret repository and reference it via settingsFrom.
receiver_emailstr
list		Yes-Recipient email addresses. Multiple addresses use array format (not limited to QQ email).
smtp_hoststrNosmtp.qq.comMail server address
smtp_portintNo465Mail server port
cc_receiver_emailstr
list		No-CC recipient email addresses. Multiple addresses use array format

Viewing Results

Analysis Report

  • After analysis completes, all issues will be printed in the logs.

  • After analysis completes, JSON and HTML reports will be generated in the tca_report directory of the current workspace for downstream steps:

    • JSON report: tca_report/tca_report.json

    • HTML report: tca_report/tca_report.html

Email Report

Analysis results can be sent to personal email. Refer to the email parameters above to complete the configuration.

Tips

How to obtain QQ email authorization code: Click here to view.

Merge Request Comments

Code analysis results triggered by pull_request will be automatically added to merge request comments.

II. Deep Analysis

Tips

  • Deep analysis supports custom analysis schemes, quality gate metrics, and continuous code issue tracking.

  • Deep analysis requires communication with the TCA platform

    • Configure the mode parameter to specify remote analysis mode node or local analysis mode local.

    • Default is node mode, which uses remote nodes to execute code analysis. Analysis tasks will be assigned by the TCA platform to online nodes.

    • Set the mode parameter to local to switch to local analysis mode (data and reports are generated locally and can be freely used).

Usage Guide

  1. First, create a team and project in TCA (skip if already exists), connect the CNB code repository, configure analysis schemes as needed, and create an analysis project. Refer to Quick Start.

  2. After connecting the repository, go to the code repository page, click Plugin Configuration to enter the TCA plugin configuration dialog, and select the CNB Cloud Native Build tab.

    Plugin Configuration

    Tips

    • Key file addresses refer to steps 3, 4, and 5. If the address already exists, skip the corresponding steps and directly input the key file address into the input box!

    • Credential information required by the plugin is sensitive personal information; keep it confidential!

  3. Create a new code repository on cnb.cool (select Key Repository as the repository type. Key repositories allow only page viewing and modification, suitable for storing keys for cloud-native builds), e.g., tca-private-config.

    Key Repository

  4. Create a YAML file in the key repository, e.g., tca-settings.yml, copy the credential information from the plugin configuration screenshot in step 2 into this file, and commit it. Click to learn File Reference Documentation.

  5. Copy the URL of this key file and paste it into the Key File Address input box in the plugin configuration screenshot from step 2. URL example: https://cnb.cool/xxx/tca-private-config/-/blob/main/tca-settings.yml.

  6. In the CNB Cloud Native Build tab, select the analysis scheme to use. If none exists, create one first. Refer to Analysis Scheme.

  7. Click the Generate .cnb.yml TCA Plugin Configuration button, navigate to the root directory of the corresponding repository on cnb.cool, copy the generated configuration content into .cnb.yml (create .cnb.yml if it does not exist; click Learn More).

(Example only; automatically generate from the plugin configuration on the TCA official website's code repository page.)

# .cnb.yml
"**":  # Triggered branch names, default to all branches, can be modified as needed
  push:  # Triggered by push, or use pull_request, etc.
    - docker:
        # Declare cache directory, /data/tca_cache/tools is the TCA plugin tool storage directory
        volumes:
          - /data/tca_cache/tools:copy-on-write
      stages:
        # Code analysis
        - name: TCA
          image: tencentcom/tca-plugin:latest
          settings:
            mode: local  # Execution mode; optional values: local (local analysis mode), node (remote node analysis mode); default: node
            org_sid: xxx  # Team ID (generated from TCA official website; no manual addition required)
            team_name: xxx  # Project name (generated from TCA official website; no manual addition required)
            scheme_id: xxx  # Analysis scheme ID (generated from TCA official website; no manual addition required)
          settingsFrom:
            # Key file reference. Ensure the code repository using this configuration has permission to access the key file; otherwise, the build will fail!
            - https://cnb.cool/xxx/tca-private-config/-/blob/main/tca-settings.yml

Parameter Description

Tips

  • The following parameters apply only to the deep analysis scenario and take precedence over parameters configured on the TCA platform.

  • Click to view TCA Plugin for the full plugin documentation and related parameters.

Core Parameters

ParameterTypeRequiredDefault ValueDescription
org_sidstrYes-Unique team identifier, obtained from the TCA platform
team_namestrYes-Unique project identifier, obtained from the TCA platform
scheme_idstrYes-Analysis scheme ID, obtained from the TCA platform
modestrNonodeAnalysis mode; optional values: local (local analysis mode), node (remote node analysis mode)
total_scanboolNofalseWhether to perform a full analysis; true for full analysis, false for incremental analysis
blockboolNotrueWhether to block the pipeline if there are quality gate failures or analysis exceptions
commentboolNotrueWhether to add code analysis results to pull_request comments
scan_dirstrNo-Analysis directory; defaults to the root directory of the repository to be analyzed. Specify a relative path to define a subdirectory as the analysis directory.
ignore_pathsstr
list		No-Paths to ignore (Unix wildcard format), specify one or more relative workspace paths to exclude. Multiple paths use array format:
1. Match src/test directory: src/test/*
2. Match test directory under root: test/*
3. Match all files ending with _test.py: *_test.py
white_pathsstr
list		No-Paths to analyze (Unix wildcard format), specify one or more relative workspace paths to include. Multiple paths use array format
pre_cmdstr or listNo-Pre-command, applicable to compiled analysis tools. Used with compilation commands and executed in the current workspace directory before the compilation command. Multiple pre-commands use array format.
build_cmdstrNo-Compilation command, applicable to compiled analysis tools. Executed in the current workspace directory.

Comparison Branch Parameters

ParameterTypeRequiredDefault ValueDescription
compare_branchstrNo-Comparison branch; only analyze incremental issues in the current branch relative to the comparison branch

Tips

  • For merge request triggers (MR/PR triggers), this parameter is ignored, and the target branch is automatically used as the comparison branch.

  • For push triggers, CNB only checks out the current branch. Since the local environment cannot access comparison branch information, incremental analysis may be affected. Therefore, use the git fetch command to pull the comparison branch before the TCA plugin. Below is an example setting compare_branch to main:

    # .cnb.yml
feat/dev:  # Triggered branch name; modify to the actual branch name
  push:  # Triggered by push
    - docker:
        # Declare cache directory, /data/tca_cache/tools is the TCA plugin tool storage directory
        volumes:
          - /data/tca_cache/tools:copy-on-write
      stages:
        # Pull comparison branch
        - name: fetch compare branch
          script: git fetch origin main  # Modify `main` to the actual comparison branch name
        # Code analysis
        - name: TCA
          image: tencentcom/tca-plugin:latest
          settings:
            mode: local
            compare_branch: main  # Comparison branch name; modify to the actual branch name
            org_sid: xxx  # Team ID, obtained from TCA official website
            team_name: xxx  # Project name, obtained from TCA official website
            scheme_id: xxx  # Analysis scheme ID, obtained from TCA official website
            total_warning: 0       # Quality gate: total issues (critical + error + warning) ≤ 0
          settingsFrom:
            - https://cnb.cool/xxx/tca-private-config/-/blob/main/tca-settings.yml

Quality Gate Parameters

Tips

  • Only applicable to mode: local (local analysis mode only!).

  • When block: true, the pipeline is blocked if the quality gate fails.

  • For remote analysis mode, configure gate metrics on the TCA platform's Analysis Scheme - Quality Gate page.

ParameterTypeRequiredDescription
total_fatalnumberNoCritical issue metric (issue count: critical), requires code inspection. Integer, recommended value: 0
total_errornumberNoError issue metric (issue count: critical + error), requires code inspection. Integer, recommended value: 0
total_warningnumberNoWarning issue metric (issue count: critical + error + warning), requires code inspection. Integer, recommended value: 0
total_infonumberNoInfo issue metric (issue count: critical + error + warning + info), requires code inspection. Integer, recommended value: 0
worse_cc_file_numnumberNoNumber of files with increased cyclomatic complexity, requires cyclomatic complexity analysis. Integer, recommended value: 0
duplicate_ratenumberNoCode duplication rate, requires duplicate code analysis. Integer, recommended value: 3

Email Parameters

Same as "Fast Analysis - Email Parameters".

Viewing Results

Analysis Report

  • Directly navigate to the TCA platform to view detailed results.

  • Local analysis mode only: Data and reports are generated locally. After analysis completes, JSON and HTML reports will be output to the tca_report directory of the current workspace for downstream steps:

    • JSON report: tca_report/tca_report.json

    • HTML report: tca_report/tca_report.html

Email Report

Same as "Fast Analysis - Email Report".

Merge Request Comments

Code analysis results triggered by pull_request will be automatically added to merge request comments.

Last Updated::
Contributors: faberihe