Auto-register project

Auto-register project integrates Code Security scanning into your GitLab CI/CD workflow. When code is pushed to the default branch or a Merge Request (MR) is created, the system automatically runs a security scan and posts the results as a comment on the MR page, helping teams identify and fix vulnerabilities before code is merged.

Background

Auto-register project is designed for development teams whose code is hosted on GitLab. By triggering code security scans through the GitLab CI/CD pipeline, security detection is embedded into daily development workflows without the need to manually upload code archives.

Compared with Manual upload scan, auto-register project is better suited for continuous integration scenarios:

Comparison	Auto-register project	Create project manually
Use case	Code is hosted on GitLab and requires continuous integration security detection.	Code is not hosted in a Git repository, or a one-time/ad-hoc scan is required.
Trigger	Automatically triggered when code is pushed to the default branch or an MR is created.	Triggered by manually uploading a code archive.
Target users	DevOps engineers and continuous integration teams.	Developers and security teams for ad-hoc testing.

Auto-register project supports two scanning capabilities: Static Application Security Testing (SAST) and Software Composition Analysis (SCA). For details, see Static Application Security Testing (SAST) and Software Composition Analysis (SCA).

Prerequisites

Code Security is activated.
You have RAM management permissions on your Alibaba Cloud account for creating access credentials.
You have administrative permissions on your GitLab instance (Premium/Ultimate or CE Free Edition) for configuring CI/CD variables and pipelines.
GitLab Runner is deployed and running.

Step 1: Create a project and open the onboarding page

Log on to the Code Security console.
On the Project List page, click Create Project.
In the pop-up menu, select Auto Registration.
The system redirects you to the GitLab CI Integration Wizard page.

The onboarding page contains four steps: Get Credentials, Scan Configuration, Configure Variables, and Verify Integration. Follow the steps below to complete the configuration.

Step 2: Get AK/SK credentials

You need to create a RAM user with Code Security service permissions in the RAM console and obtain the AccessKey ID and AccessKey Secret. This step corresponds to the Get Credentials step in the onboarding wizard.

Create a permission policy

Log on to the RAM console.
In the left-side navigation pane, choose Permissions > Policies.

Click Create Policy, select the JSON Editor editing mode, enter the following policy content, and then save the policy:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "yundun-codesec:*",
      "Resource": "*"
    }
  ]
}

Create a RAM user

In the left-side navigation pane, choose Identities > Users, and then click Create User.
In Access Mode, select Permanent AccessKey, and then complete the user creation.
After the user is created, immediately save the AccessKey ID and AccessKey Secret. You cannot view them again after you close the page.

Attach the permission policy

In the user list, find the RAM user that you created and click Add Permissions.
Select the custom policy that you created in the previous step and complete the attachment.

After the preceding operations are complete, click Next on the onboarding page to proceed to scan configuration.

Step 3: Scan configuration

In the Scan Configuration step of the onboarding wizard, complete the following configurations based on your business needs.

GitLab version

Select your GitLab version:

Premium/Ultimate: Enterprise edition of GitLab. Supports incremental and full scans.
CE (Free): Community edition of GitLab. Supports basic scan features.

Scan strategy (select at least one)

Branch Merge Scan: Automatically triggers a scan when an MR is created to quickly verify the security of changed code.
Full Scan: Triggers a full scan when code is pushed to the default branch to ensure the security baseline of the main branch.

Scan scope

Selected Projects: Enables scanning only for the specified GitLab projects. You need to configure the CI file in each target repository.
Full Coverage: Covers all projects in the GitLab instance.

GitLab Runner configuration

Select the executor type based on your Runner type. You can view the registered Runner information under Settings > CI/CD > Runners of your project:

Docker executor: Recommended. Scans run in containers. The Runner must use the Docker executor.
Shell executor: Scans run directly on the Runner host.

Regardless of the executor type, the Runner must have internet access to pull the scan image and upload results.

Deployment instructions

The system dynamically generates deployment instructions and a YAML template based on your selections. The following example uses the Full Coverage (Admin) mode:

Create a template repository on GitLab (such as yundun-codesec/templates) and save the YAML provided by the wizard as yundun-codesec-config.yml.
Go to Admin Area > Settings > CI/CD > Required pipeline configuration.
Enter the template path: yundun-codesec-config.yml@yundun-codesec/templates.
After saving, the scan job is automatically included in the pipelines of all projects.
To exempt a specific project, add the variable YUNDUN_CODESEC_SKIP=true in CI/CD Variables of that project.

After the scan configuration is complete, click Next to proceed to variable configuration.

Step 4: Configure CI/CD variables

In the Configure Variables step of the onboarding wizard, configure CI/CD variables in GitLab as described so that the scan tool can connect to the Code Security service and the GitLab API.

Global variables (instance-level or group-level)

In GitLab, go to Admin Area > Settings > CI/CD > Variables (instance-level, shared by all projects) and configure the following variables:

Variable	Description	Configuration requirement
YUNDUN_CODESEC_OPENAPI_AK	The AccessKey ID of the RAM user.	Required. You must select Masked.
YUNDUN_CODESEC_OPENAPI_SECRET	The AccessKey Secret of the RAM user.	Required. You must select Masked.
YUNDUN_CODESEC_OPENAPI_ENDPOINT	The OpenAPI endpoint of the Code Security service.	Required. Use the endpoint provided on the onboarding page.
GIT_SSL_NO_VERIFY	Set this variable to `true` to skip TLS certificate verification.	Required when a self-signed certificate is used. Otherwise, the job fails in the clone stage.

Project-level variables

In each project, go to Settings > CI/CD > Variables and configure the following variables:

Variable	Description	Configuration requirement
YUNDUN_CODESEC_GITLAB_TOKEN	A GitLab access token used to post scan result comments on the MR page.	The token must have the api permission. We recommend that you use a project access token (Settings > Access Tokens, Developer role).

Important

Security tips:

You must select Masked for YUNDUN_CODESEC_OPENAPI_AK and YUNDUN_CODESEC_OPENAPI_SECRET to prevent them from being exposed in CI logs.
We recommend that you do not select Protected: MR pipelines run on feature branches, while protected variables are available only in pipelines on protected branches. Selecting Protected causes MR scans to fail to read the credentials.
If YUNDUN_CODESEC_GITLAB_TOKEN is not configured, MR comments do not take effect, but scanning and report generation are not affected.

After the variable configuration is complete, click Next to proceed to verify integration.

Step 5: Configure .gitlab-ci.yml

Add a security scan job to the .gitlab-ci.yml file in the project root directory. The following example uses the Full Coverage mode:

stages:
  - security

yundun-codesec-scan:
  stage: security
  image: codesec-registry.cn-hangzhou.cr.aliyuncs.com/codesec/krypton-cli:latest
  script:
    - krypton-cli scan --gl-sast-report=gl-sast-report.json --gl-dependency-scanning-report=gl-dependency-scanning-report.json --mr-comment
  artifacts:
    reports:
      sast: gl-sast-report.json
      dependency_scanning: gl-dependency-scanning-report.json
  when: always

Key parameters:

--gl-sast-report: generates the SAST scan report file.
--gl-dependency-scanning-report: generates the dependency scan report file.
--mr-comment: automatically posts scan result comments on the MR page.

After the configuration is complete, click Next to proceed to verify integration.

Step 6: Verify integration

In the Verify Integration step of the onboarding wizard, use the following methods to verify whether the integration is successful.

Trigger a scan

Use one of the following methods to trigger a scan:

Create a Merge Request (triggers an incremental MR scan to quickly verify the security of changed code).
Push code to the default branch (triggers a full scan to ensure the security baseline of the main branch).

Verify in the Code Security console

Log on to the Code Security console.
On the Project List page, confirm that the GitLab project is listed and that the integration type is GitLab CI.
Go to the project details page and view Task List to confirm that a scan record exists. After the scan is complete, you can view vulnerability details, severity levels, and fix suggestions in the scan results.

Verify in GitLab

On the Build > Pipelines page of your project (or CI/CD > Pipelines in earlier versions), click the latest pipeline and confirm that a job named yundun-codesec-scan appears.
In the Artifacts section of the job details page, confirm that scan report files such as gl-sast-report.json have been generated.
On the MR page, confirm that Code Security scan result comments appear in the comment section, including a summary of new and fixed vulnerabilities (requires YUNDUN_CODESEC_GITLAB_TOKEN to be configured).

After the verification succeeds, click Done to exit the onboarding wizard.