---
title: "Gitlab CI"
diataxis: how-to
applies_to:
  product: "nirmata-control-hub"
audience: ["platform-engineer","cluster-admin"]
last_updated: 2026-03-25
url: https://docs.nirmata.io/docs/control-hub/how-to/pipelinescanning/gitlab-ci/
---


`nctl` integrates with GitLab CI and allows scanning against security team-defined policies, which ensures addressing of misconfigurations in the pipeline alongside other tests and vulnerability scanning. The `nctl-scan` job triggers the scan. In case of a failure, the entire job can be configured to fail, meaning that the test pipeline will fail and users will get quick feedback on their changes. Upon successful completion of the job, the scan results are published to the Nirmata Control Hub for viewing. Nirmata Control Hub provides insights to platform administrators on the overall compliance of different code repositories in their organization. Learn more about GitLab CI pipelines and their configuration from this [official documentation](https://docs.gitlab.com/ee/ci/pipelines/).

### Understanding the GitLab CI Workflow

To see pipeline scanning with GitLab CI in action:

#### Install `nctl` in the GitLab pipeline

Add the `install nctl` job to the `gitlab-ci.yml` file in the repository. The job installs the nctl CLI and stores it as an artifact for future jobs. The following code does that:

````bash
install-nctl: 
  stage: install
  script:
    - echo "Downloading and Installing NCTL 4.2.0"
    - curl -O -L -s https://nirmata-downloads.s3.us-east-2.amazonaws.com/nctl/nctl_4.0.2/nctl_4.2.0_linux_386.zip
    - unzip *.zip
    - echo "Verify Installation"
    - chmod 755 ./nctl
    - ./nctl version
  artifacts:
    paths:
    - ./nctl
````

#### Scan Repository files for misconfigurations

The `nctl-scan-repo` job scans the configuration files in the repository for any misconfigurations. The `–policies` argument points to the directory containing security policies.
>Note: The policies can also be stored in a different GitLab repository. Refer to the sample list of policies [here](https://github.com/nirmata/kyverno-policies).

After the execution of this job, the pipeline will fail if there are misconfigurations which will force the developer to debug and fix the issue at the source.

````bash
nctl-scan-repo:   # This job scans config files for misconfigurations.
  stage: scan    # It only starts when the job in the install stage completes successfully.
  dependencies:
    - install-nctl
  script:
    - echo "Running nctl scan"
    - pwd
    - git checkout main # Checkout the branch of choice or use pipeline variables to specify the branch.
    - ./nctl scan repository --policies ./policy.yaml
````
>Note: Setting the branch variable through `git checkout main` is specific only for GitLab.

This pipeline runs in two stages: `install-nctl` and `scan`. Both can be visualized in the GitLab UI. The below image represents the same.

![image](/images/GitLab-CI.png)