Register with GitLab

Updated at:
Copy as MD

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:

ComparisonAuto-register projectCreate project manually
Use caseCode 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.
TriggerAutomatically triggered when code is merged into the default branch or an MR is created.Triggered by manually uploading a code archive.
Target usersDevOps 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

  1. Log on to the Code Security console.

  2. On the Project List page, click Create Project.

  3. From the pop-up menu, select Auto Registration.

  4. 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

  1. Log on to the Resource Access Management console.

  2. In the left-side navigation pane, choose Permissions > Policies.

  3. 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

  1. In the left-side navigation pane, choose Identities > Users, and then click Create User.

  2. Under Access Mode, select Permanent AccessKey to create the user.

  3. 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

  1. In the user list, find the RAM user that you created and click Add Permissions.

  2. 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:

  1. Create a template repository on GitLab (such as yundun-codesec/templates), and save the YAML provided by the wizard as yundun-codesec-config.yml.

  2. Go to Admin Area > Settings > CI/CD > Required pipeline configuration.

  3. Enter the template path: yundun-codesec-config.yml@yundun-codesec/templates.

  4. After saving, the scan job is automatically included in the pipelines of all projects.

  5. To exempt a specific project, add the following variable to that project's CI/CD Variables: YUNDUN_CODESEC_SKIP=true.

    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 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:

VariableDescriptionConfiguration requirement
YUNDUN_CODESEC_OPENAPI_AKThe AccessKey ID of the RAM user.Required. Select Masked.
YUNDUN_CODESEC_OPENAPI_SECRETThe AccessKey secret of the RAM user.Required. Select Masked.
YUNDUN_CODESEC_OPENAPI_ENDPOINTThe OpenAPI endpoint of the Code Security service.Required. Use the endpoint provided on the wizard page.
GIT_SSL_NO_VERIFYSet 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:

VariableDescriptionConfiguration requirement
YUNDUN_CODESEC_GITLAB_TOKENA 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_AK and YUNDUN_CODESEC_OPENAPI_SECRET must 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 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, first deploy the scan job on the GitLab side by following Step 5, and then click Next to proceed to verify integration.

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: always

Key parameters:

  • --gl-sast-report: Generates the SAST scan report file.

  • --gl-dependency-scanning-report: Generates the dependency scanning report file.

  • --mr-comment: Automatically posts scan result comments on the MR page.

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

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

  1. Log on to the Code Security console.

  2. On the Project List page, confirm that the GitLab project appears and that the integration type is GitLab CI.

  3. 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

  1. 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-scan appears.

  2. On the job details page, verify that Artifacts includes generated scan report files such as gl-sast-report.json.

  3. 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 YUNDUN_CODESEC_GITLAB_TOKEN).

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