{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreicqki6pwn47wp7wf4sfoveurftvgrlj4uhskum4ek7z35rym6znbi",
    "uri": "at://did:plc:5c4fdh2tkwp6vnd4g4oxyqyu/app.bsky.feed.post/3mgflaqqdtw42"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreigsodglwly7chbcvvesy4m4qqxxk54rzyhvznyluffocpgbcwdah4"
    },
    "mimeType": "image/png",
    "size": 161480
  },
  "path": "/blog/complete-guide-to-gitlab-container-scanning/",
  "publishedAt": "2026-03-05T00:00:00.000Z",
  "site": "https://about.gitlab.com",
  "tags": [
    "Documentation",
    "Security widget",
    "Vulnerability Report",
    "Vulnerability Details",
    "Dependency List",
    "GitLab Kubernetes Agent",
    "scan execution policy",
    "Scan execution policies",
    "Pipeline execution policies",
    "Merge request approval policies",
    "GitLab Security and Governance Solutions Page"
  ],
  "textContent": "Container vulnerabilities don't wait for your next deployment. They can emerge at any point, including when you build an image or while containers run in production. GitLab addresses this reality with multiple container scanning approaches, each designed for different stages of your container lifecycle.\n\nIn this guide, we'll explore the different types of container scanning GitLab offers, how to enable each one, and common configurations to get you started.\n\n## Why container scanning matters\n\nSecurity vulnerabilities in container images create risk throughout your application lifecycle. Base images, OS packages, and application dependencies can all harbor vulnerabilities that attackers actively exploit. Container scanning detects these risks early, before they reach production, and provides remediation paths when available.\n\nContainer scanning is a critical component of Software Composition Analysis (SCA), helping you understand and secure the external dependencies your containerized applications rely on.\n\n## The five types of GitLab Container Scanning\n\nGitLab offers five distinct container scanning approaches, each serving a specific purpose in your security strategy.\n\n### 1. Pipeline-based Container Scanning\n\n  * What it does: Scans container images during your CI/CD pipeline execution, catching vulnerabilities before deployment\n  * Best for: Shift-left security, blocking vulnerable images from reaching production\n  * Tier availability: Free, Premium, and Ultimate (with enhanced features in Ultimate)\n  * Documentation\n\n\n\nGitLab uses the Trivy security scanner to analyze container images for known vulnerabilities. When your pipeline runs, the scanner examines your images and generates a detailed report.\n\n#### How to enable pipeline-based Container Scanning\n\n**Option A: Preconfigured merge request**\n\n  * Navigate to **Secure > Security configuration** in your project.\n  * Find the \"Container Scanning\" row.\n  * Select **Configure with a merge request**.\n  * This automatically creates a merge request with the necessary configuration.\n\n\n\n**Option B: Manual configuration**\n\n  * Add the following to your `.gitlab-ci.yml`:\n\n\n\n\n    include:  - template: Jobs/Container-Scanning.gitlab-ci.yml\n\n#### Common configurations\n\n**Scan a specific image:**\n\nTo scan a specific image, overwrite the `CS_IMAGE` variable in the `container_scanning` job.\n\n\n    include:  - template: Jobs/Container-Scanning.gitlab-ci.yml  container_scanning:  variables:  CS_IMAGE: myregistry.com/myapp:latest\n\n**Filter by severity threshold:**\n\nTo only find vulnerabilities with a certain severity criteria, overwrite the `CS_SEVERITY_THRESHOLD` variable in the `container_scanning` job. In the example below, only vulnerabilities with a severity of **High** or greater will be displayed.\n\n\n    include:  - template: Jobs/Container-Scanning.gitlab-ci.yml  container_scanning:  variables:  CS_SEVERITY_THRESHOLD: \"HIGH\"\n\n#### Viewing vulnerabilities in a merge request\n\nViewing Container Scanning vulnerabilities directly within merge requests makes security reviews seamless and efficient. Once Container Scanning is configured in your CI/CD pipeline, GitLab automatically display detected vulnerabilities in the merge request's Security widget.\n\n  * Navigate to any merge request and scroll to the \"Security Scanning\" section to see a summary of newly introduced and existing vulnerabilities found in your container images.\n  * Click on a **Vulnerability** to access detailed information about the finding, including severity level, affected packages, and available remediation guidance.\n\n\n\nThis visibility enables developers and security teams to catch and address container vulnerabilities before they reach production, making security an integral part of your code review process rather than a separate gate.\n\n#### Viewing vulnerabilities in Vulnerability Report\n\nBeyond merge request reviews, GitLab provides a centralized Vulnerability Report that gives security teams comprehensive visibility across all Container Scanning findings in your project.\n\n  * Access this report by navigating to **Security & Compliance > Vulnerability Report** in your project sidebar.\n  * Here you'll find an aggregated view of all container vulnerabilities detected across your branches, with powerful filtering options to sort by severity, status, scanner type, or specific container images.\n  * You can click on a vulnerabilty to access its Vulnerablity page.\n\n\n\nVulnerability Details shows exactly which container images and layers are impacted, making it easier to trace the vulnerability back to its source. You can assign vulnerabilities to team members, change their status (detected, confirmed, resolved, dismissed), add comments for collaboration, and link related issues for tracking remediation work.\n\nThis workflow transforms vulnerability management from a spreadsheet exercise into an integrated part of your development process, ensuring that container security findings are tracked, prioritized, and resolved systematically.\n\n#### View the Dependency List\n\nGitLab's Dependency List provides a comprehensive software bill of materials (SBOM) that catalogs every component within your container images, giving you complete transparency into your software supply chain.\n\n  * Navigate to **Security & Compliance > Dependency List** to access an inventory of all packages, libraries, and dependencies detected by Container Scanning across your project.\n  * This view is invaluable for understanding what's actually running inside your containers, from base OS packages to application-level dependencies.\n\n\n\nYou can filter the list by package manager, license type, or vulnerability status to quickly identify which components pose security risks or compliance concerns. Each dependency entry shows associated vulnerabilities, allowing you to understand security issues in the context of your actual software components rather than as isolated findings.\n\n### 2. Container Scanning for Registry\n\n  * What it does: Automatically scans images pushed to your GitLab Container Registry with the `latest` tag\n  * Best for: Continuous monitoring of registry images without manual pipeline triggers\n  * Tier availability: Ultimate only\n  * Documentation\n\n\n\nWhen you push a container image tagged `latest`, GitLab's security policy bot automatically triggers a scan against the default branch. Unlike pipeline-based scanning, this approach works with Continuous Vulnerability Scanning to monitor for newly published advisories.\n\n#### How to enable Container Scanning for Registry\n\n  1. Navigate to **Secure > Security configuration**.\n  2. Scroll to the **Container Scanning For Registry** section.\n  3. Toggle the feature on.\n\n\n\n#### Prerequisites\n\n  * Maintainer role or higher in the project\n  * Project must not be empty (requires at least one commit on the default branch)\n  * Container Registry notifications must be configured\n  * Package Metadata Database must be configured (enabled by default on GitLab.com)\n\n\n\nVulnerabilities appear under the **Container Registry vulnerabilities** tab in your Vulnerability Report.\n\n### 3. Multi-Container Scanning\n\n  * What it does: Scans multiple container images in parallel within a single pipeline\n  * Best for: Microservices architectures and projects with multiple container images\n  * Tier availability: Free, Premium, and Ultimate (currently in Beta)\n  * Documentation\n\n\n\nMulti-Container Scanning uses dynamic child pipelines to run scans concurrently, significantly reducing overall pipeline execution time when you need to scan multiple images.\n\n#### How to enable Multi-Container scanning\n\n  1. Create a `.gitlab-multi-image.yml` file in your repository root:\n\n\n\n\n    scanTargets:  - name: alpine  tag: \"3.19\"  - name: python  tag: \"3.9-slim\"  - name: nginx  tag: \"1.25\"\n\n  2. Include the template in your `.gitlab-ci.yml`:\n\n\n\n\n    include:  - template: Jobs/Multi-Container-Scanning.latest.gitlab-ci.yml\n\n#### Advanced configuration\n\n**Scan images from private registries:**\n\n\n     auths:  registry.gitlab.com:  username: ${CI_REGISTRY_USER}  password: ${CI_REGISTRY_PASSWORD}  scanTargets:  - name: registry.gitlab.com/private/image  tag: latest\n\n**Include license information:**\n\n\n     includeLicenses: true  scanTargets:  - name: postgres  tag: \"15-alpine\"\n\n### 4. Continuous Vulnerability Scanning\n\n  * What it does: Automatically creates vulnerabilities when new security advisories are published, no pipeline required\n  * Best for: Proactive security monitoring between deployments\n  * Tier availability: Ultimate only\n  * Documentation\n\n\n\nTraditional scanning only catches vulnerabilities at scan time. But what happens when a new CVE is published tomorrow for a package you scanned yesterday? Continuous Vulnerability Scanning solves this by monitoring the GitLab Advisory Database and automatically creating vulnerability records when new advisories affect your components.\n\n#### How it works\n\n  1. Your Container Scanning or Dependency Scanning job generates a CycloneDX SBOM.\n  2. GitLab registers your project's components from this SBOM.\n  3. When new advisories are published, GitLab checks if your components are affected.\n  4. Vulnerabilities are automatically created in your vulnerability report.\n\n\n\n#### Key considerations\n\n  * Scans run via background jobs (Sidekiq), not CI pipelines.\n  * Only advisories published within the last 14 days are considered for new component detection.\n  * Vulnerabilities use \"GitLab SBoM Vulnerability Scanner\" as the scanner name.\n  * To mark vulnerabilities as resolved, you still need to run a pipeline-based scan.\n\n\n\n### 5. Operational Container Scanning\n\n  * What it does: Scans running containers in your Kubernetes cluster on a scheduled cadence\n  * Best for: Post-deployment security monitoring and runtime vulnerability detection\n  * Tier availability: Ultimate only\n  * Documentation\n\n\n\nOperational Container Scanning bridges the gap between build-time security and runtime security. Using the GitLab Agent for Kubernetes, it scans containers actually running in your clusters—catching vulnerabilities that emerge after deployment.\n\n#### How to enable Operational Container Scanning\n\nIf you are using the GitLab Kubernetes Agent, you can add the following to your agent configuration file:\n\n\n    container_scanning:  cadence: '0 0 * * *' # Daily at midnight  vulnerability_report:  namespaces:  include:  - production  - staging\n\nYou can also create a scan execution policy that enforces scanning on a schedule by the GitLab Kubernetes Agent.\n\n#### Viewing results\n\n  * Navigate to **Operate > Kubernetes clusters**.\n  * Select the **Agent** tab, and choose your agent.\n  * Then select the **Security** tab to view cluster vulnerabilities.\n  * Results also appear under the **Operational Vulnerabilities** tab in the **Vulnerability Report**.\n\n\n\n## Enhancing posture with GitLab Security Policies\n\nGitLab Security Policies enable you to enforce consistent security standards across your container workflows through automated, policy-driven controls. These policies shift security left by embedding requirements directly into your development pipeline, ensuring vulnerabilities are caught and addressed before code reaches production.\n\n#### Scan execution and pipeline policies\n\nScan execution policies automate when and how Container Scanning runs across your projects. Define policies that trigger container scans on every merge request, schedule recurring scans of your main branch, and more. These policies ensure comprehensive coverage without relying on developers to manually configure scanning in each project's CI/CD pipeline.\n\nYou can specify which scanner versions to use and configure scanning parameters centrally, maintaining consistency across your organization while adapting to new container security threats.\n\nPipeline execution policies provide flexible controls for injecting (or overriding) custom jobs into a pipeline based on your compliance needs.\n\nUse these policies to automatically inject Container Scanning jobs into your pipeline, fail builds when container vulnerabilities exceed your risk tolerance, trigger additional security checks for specific branches or tags, or enforce compliance requirements for container images destined for production environments. Pipeline execution policies act as automated guardrails, ensuring your security standards are consistently applied across all container deployments without manual intervention.\n\n#### Merge request approval policies\n\nMerge request approval policies enforce security gates by requiring designated approvers to review and sign off on merge requests containing container vulnerabilities.\n\nConfigure policies that block merge when critical or high-severity vulnerabilities are detected, or require security team approval for any merge request introducing new container findings. These policies prevent vulnerable container images from advancing through your pipeline while maintaining development velocity for low-risk changes.\n\n## Choosing the right approach\n\nScanning Type| When to Use| Key Benefit\n---|---|---\nPipeline-based| Every build| Shift-left security, blocks vulnerable builds\nRegistry scanning| Continuous monitoring| Catches new CVEs in stored images\nMulti-container| Microservices| Parallel scanning, faster pipelines\nContinuous vulnerability| Between deployments| Proactive advisory monitoring\nOperational| Production monitoring| Runtime vulnerability detection\n\nFor comprehensive security, consider combining multiple approaches. Use pipeline-based scanning to catch issues during development, container scanning for registry for continuous monitoring, and operational scanning for production visibility.\n\n## Get started today\n\nThe fastest path to container security is enabling pipeline-based scanning:\n\n  1. Navigate to your project's **Secure > Security configuration**.\n  2. Click **Configure with a merge request** for Container Scanning.\n  3. Merge the resulting merge request.\n  4. Your next pipeline will include vulnerability scanning.\n\n\n\nFrom there, layer in additional scanning types based on your security requirements and GitLab tier.\n\nContainer security isn't a one-time activity, it's an ongoing process. With GitLab's comprehensive container scanning capabilities, you can detect vulnerabilities at every stage of your container lifecycle, from build to runtime.\n\n> For more information on how GitLab can help enhance your security posture, visit the GitLab Security and Governance Solutions Page.",
  "title": "A complete guide to GitLab Container Scanning",
  "updatedAt": "2026-03-05T00:00:00.000Z"
}