Register with GitLab
Registering with GitLab integrates Code Security scanning into your GitLab CI/CD workflow. When code is merged into the default branch or a merge request (MR) is created, the system automatically runs a scan and posts the results as a comment on the MR page. This helps teams find and fix security vulnerabilities before code is merged.
Background information
The auto-register project feature is designed for development teams whose code is hosted on GitLab. It integrates security scanning into daily development workflows without the need to manually upload code archives.
Compared with Create project manually, the auto-register project feature is better suited for continuous integration use cases:
| Comparison | Auto-register project | Create project manually |
| Use case | Code is hosted on GitLab and requires continuous integration security scanning. | Code is not hosted in a Git repository, or a one-time or ad hoc scan is required. |
| Trigger | Automatically triggered when code is merged into 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 that need ad hoc scans. |
The auto-register project feature supports two scanning capabilities. For more information about each capability, 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.
From 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 in this topic to complete the configuration.
Step 2: Get your AccessKey credentials
Create a RAM user with Code Security service permissions in the RAM console and obtain its AccessKey ID and AccessKey secret. This step corresponds to the Get Credentials step in the wizard.
Create an access policy
Log on to the Resource Access Management console.
In the left-side navigation pane, choose Permissions > Policies.
Click Create Policy, select JSON Editor 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.
Under Access Mode, select Permanent AccessKey to create the user.
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 access 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 wizard page to proceed to scan configuration.
Step 3: Scan configuration
In the Scan Configuration step of the wizard, complete the following configurations based on your business needs.
GitLab version
Select the GitLab version type:
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 that matches your Runner type (for information about registered Runners, see the project's Settings > CI/CD > Runners):
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 asyundun-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 following variable to that project's CI/CD Variables:
After the scan configuration is complete, click Next to proceed to variable configuration.YUNDUN_CODESEC_SKIP=true.
Step 4: Configure CI/CD variables
In the Configure Variables step of the wizard, configure GitLab CI/CD variables as described so that the scan tool can connect to the Code Security service and the GitLab API.
Global variables (instance-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. Select Masked. |
YUNDUN_CODESEC_OPENAPI_SECRET | The AccessKey secret of the RAM user. | Required. Select Masked. |
YUNDUN_CODESEC_OPENAPI_ENDPOINT | The OpenAPI endpoint of the Code Security service. | Required. Use the endpoint provided on the wizard page. |
GIT_SSL_NO_VERIFY | Set 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. (Recommended) Use a Project Access Token (Settings > Access Tokens, Developer role). |
Security tips:
YUNDUN_CODESEC_OPENAPI_AKandYUNDUN_CODESEC_OPENAPI_SECRETmust have Masked selected to prevent them from being exposed in CI logs.Do not select Protected: MR pipelines run on feature branches, and protected variables are available only to pipelines on protected branches. Selecting Protected causes MR scans to fail to read the credentials.
If
After the variable configuration is complete, first deploy the scan job on the GitLab side by following Step 5, and then click Next to proceed to verify integration.YUNDUN_CODESEC_GITLAB_TOKENis not configured, MR comments do not take effect, but scanning and report generation are not affected.
Step 5: Deploy the security scan job
This step is performed on the GitLab side and is not part of the wizard page flow. Choose a deployment method based on the scan scope. If you select Specified Projects, add a security scan job to the .gitlab-ci.yml file in the root directory of the target project. If you select Full Coverage, an administrator saves the YAML generated by the wizard as an instance-level template by following the deployment instructions in Step 3. The following example shows the YAML definition of the scan job:
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: alwaysKey parameters:
--gl-sast-report: Generates the SAST scan report file.--gl-dependency-scanning-report: Generates the dependency scanning report file.
After the deployment is complete, click Next to proceed to verify integration.--mr-comment: Automatically posts scan result comments on the MR page.
Step 6: Verify integration
In the Verify Integration step of the 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 appears and that the integration type is GitLab CI.
Open the project details and check 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 project's Build > Pipelines page (or CI/CD > Pipelines in earlier versions), click the latest pipeline and confirm that a job named
yundun-codesec-scanappears.On the job details page, verify that Artifacts includes generated scan report files such as
gl-sast-report.json.On the MR page, confirm that a Code Security scan result comment appears in the comment section, including a summary of new and fixed vulnerabilities (requires
After the verification succeeds, click Done to exit the wizard.YUNDUN_CODESEC_GITLAB_TOKEN).