> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codeant.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab

> Set up GitLab CI workflow for CodeAnt CI scan.

# CodeAnt CI Scan for GitLab

A GitLab CI/CD configuration to run CodeAnt security and code quality analysis on your repository.

## Features

* 🧠 Automated security and code quality scanning
* 🔍 Deep vulnerability and dependency analysis
* 📊 Comprehensive reports and actionable insights
* ⚡ Fast setup - integrate in under a minute
* 🔄 Supports push, merge requests, and default branch commits

## Quick Start (Recommended)

Add this to your project's `.gitlab-ci.yml` file:

```yaml theme={null}
include:
  - remote: 'https://gitlab.com/codeant-pipelines/ci-scan-gitlab/-/raw/main/.gitlab-ci.yml'

variables:
  ACCESS_TOKEN_GITLAB: "$ACCESS_TOKEN_GITLAB"        # Required - set this in GitLab CI/CD Variables
  SCANNERS: "sast,sca"                 # Optional (default sast,sca)
  INCLUDE_PATHS: "src/,lib/"           # Optional
  EXCLUDE_PATHS: "tests/,docs/"        # Optional
  SCAN_TIMEOUT: "600"                  # Optional (default 300 seconds)
```

This will automatically run the `codeant_scan` job defined in the shared CodeAnt pipeline template.

## Setup Guide

### 1. Get Your GitLab Access Token

1. Log in to your GitLab account
2. Go to **Edit profile (User Settings) > Access Tokens**
3. Create a new token with the `api` scope (This grants full read/write access to the API and repositories)
4. Copy the token

### 2. Add Token to GitLab CI/CD Variables

1. Go to **Settings > CI/CD > Variables**
2. Click **Add Variable**
3. Fill in the details:
   * **Key:** `ACCESS_TOKEN_GITLAB`
   * **Value:** your GitLab token
   * **Protect variable:** Yes (Recommended)
   * **Mask variable:** Yes (Recommended)
4. Click **Add Variable**

### 3. Commit and Push

Once your `.gitlab-ci.yml` file includes the CodeAnt template, push it to your repository. Your next push, merge request, or main branch commit will automatically trigger a scan.

## Advanced Usage

You can customize how CodeAnt scans your repository by overriding variables:

```yaml theme={null}
include:
  - remote: 'https://gitlab.com/codeant-pipelines/ci-scan-gitlab/-/raw/main/.gitlab-ci.yml'

variables:
  ACCESS_TOKEN_GITLAB: "$ACCESS_TOKEN_GITLAB"
  SCANNERS: "sast,sca"                  # Customize scanners (all, sast, sast,secrets, etc.)
  INCLUDE_PATHS: "src/,backend/"
  EXCLUDE_PATHS: "tests/,vendor/"
  SCAN_TIMEOUT: "900"                   # Timeout in seconds
```

## Scanner Options

🔍 **Available Scanners:**

The `SCANNERS` variable allows you to customize which security scanners run during analysis:

* **`sast`** - Static Application Security Testing (code vulnerabilities)
* **`sca`** - Software Composition Analysis (dependency vulnerabilities)
* **`secrets`** - Secret detection (API keys, passwords, tokens)
* **`antipatterns`** - Code quality and duplicate code detection
* **`iac`** - Infrastructure as Code security (Terraform, CloudFormation, etc.)
* **`all`** - Run all available scanners

**Default:** If not specified, runs `sast,sca`

**Examples:**

* Run all scanners: `SCANNERS: 'all'`
* Only SAST: `SCANNERS: 'sast'`
* SAST + Secrets: `SCANNERS: 'sast,secrets'`
* Full security suite: `SCANNERS: 'sast,sca,secrets,iac'`

## Example Configurations

### Run All Scanners

```yaml theme={null}
include:
  - remote: 'https://gitlab.com/codeant-pipelines/ci-scan-gitlab/-/raw/main/.gitlab-ci.yml'

variables:
  ACCESS_TOKEN_GITLAB: "$ACCESS_TOKEN_GITLAB"
  SCANNERS: "all"  # Runs all scanner types
```

### Security-Focused Scan

```yaml theme={null}
include:
  - remote: 'https://gitlab.com/codeant-pipelines/ci-scan-gitlab/-/raw/main/.gitlab-ci.yml'

variables:
  ACCESS_TOKEN_GITLAB: "$ACCESS_TOKEN_GITLAB"
  SCANNERS: "sast,secrets"  # Only code vulnerabilities and secret detection
```

### Scan on Push and Merge Requests (Default)

```yaml theme={null}
codeant_scan:
  # ... configuration
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_PIPELINE_SOURCE == "push"
```

### Scan Only on Main Branch and Merge Requests

```yaml theme={null}
codeant_scan:
  # ... configuration
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
```

### Scheduled Daily Scan

Create a scheduled pipeline in **CI/CD > Schedules** and use:

```yaml theme={null}
codeant_scan:
  # ... configuration
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
```

### Scan Specific Directories with Security Focus

```yaml theme={null}
codeant_scan:
  image: alpine:latest
  variables:
    SCANNERS: "sast,secrets"
    INCLUDE_PATHS: "src/,backend/"
    EXCLUDE_PATHS: "src/tests/,backend/vendor/"
  # ... rest of configuration
```

### Using a Self-Hosted CodeAnt Instance

```yaml theme={null}
codeant_scan:
  image: alpine:latest
  variables:
    API_BASE: "https://codeant.your-company.com"
    INCLUDE_PATHS: ""
    EXCLUDE_PATHS: ""
  # ... rest of configuration
```

### Increasing Scan Timeout

For large repositories that need more time to complete analysis:

```yaml theme={null}
codeant_scan:
  image: alpine:latest
  timeout: 15m  # GitLab job timeout (prevents job from running too long)
  variables:
    SCAN_TIMEOUT: "600"  # Scan script timeout in seconds (10 minutes)
    INCLUDE_PATHS: ""
    EXCLUDE_PATHS: ""
  # ... rest of configuration
```

**Timeout Options:**

* `timeout: 15m` - GitLab CI job timeout (format: 30s, 5m, 1h, 2h 30m)
* `SCAN_TIMEOUT: "600"` - CodeAnt scan timeout in seconds (default: 300)

**Recommended Values:**

* Samll repos (\< 1000 files): `SCAN_TIMEOUT: "300"` (5 minutes)
* Medium repos (1000-5000 files): `SCAN_TIMEOUT: "600"` (10 minutes)
* Large repos (>5000 files): `SCAN_TIMEOUT: "900"` (15 minutes)

### Multi-Stage Pipeline

Integrate CodeAnt scan with other pipeline stages:

```yaml theme={null}
stages:
  - security
  - test
  - build
  - deploy

codeant_scan:
  stage: security
  image: alpine:latest
  variables:
    API_BASE: "https://api.codeant.ai"
  before_script:
    - apk add --no-cache curl bash python3
  script:
    - |
      curl -sS -X GET "${API_BASE}/analysis/ci/scan/script/get" \
        --output start_scan.sh.b64
      if [ "$API_BASE" = "https://api.codeant.ai" ]; then
        base64 -d start_scan.sh.b64 > start_scan.sh
      else
        mv start_scan.sh.b64 start_scan.sh
      fi
      chmod +x start_scan.sh
      bash start_scan.sh \
        -a "$ACCESS_TOKEN_GITLAB" \
        -r "$CI_PROJECT_PATH" \
        -c "$CI_COMMIT_SHA" \
        -b "$CI_COMMIT_REF_NAME" \
        -s gitlab \
        -i "$INCLUDE_PATHS" \
        -e "$EXCLUDE_PATHS" \
        --scanners "$SCANNERS"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

unit_tests:
  stage: test
  script:
    - npm test

build_app:
  stage: build
  script:
    - npm run build

deploy_production:
  stage: deploy
  script:
    - ./deploy.sh
  only:
    - main
```

## GitLab CI Variables Used

The configuration automatically uses these GitLab predefined variables:

* **CI\_PROJECT\_PATH** - Full path of the repository (e.g., group/project)
* **CI\_COMMIT\_SHA** - The commit SHA being analyzed
* **CI\_COMMIT\_REF\_NAME** - The branch or tag name
* **CI\_PIPELINE\_SOURCE** - The source of the pipeline trigger
* **CI\_DEFAULT\_BRANCH** - The default branch of the project

## Troubleshooting

**Authentication Errors**

* Ensure your `ACCESS_TOKEN_GITLAB` is correctly set in CI/CD variables
* Verify the token hasn't expired
* Check that the token has the necessary permissions
* Confirm the variable is available (not protected when running on non-protected branches)

**Scan Failures**

* Verify your repository is accessible
* Check that the API base URL is correct
* Review the pipeline logs for specific error messages
* Ensure GitLab runners can access the CodeAnt API endpoint

**Script Download Issues**

* Verify the `API_BASE` URL is correct
* Check network connectivity and firewall rules
* Ensure the CodeAnt API endpoint is accessible from your GitLab runners

**Pipeline Not Triggering**

* Check that `.gitlab-ci.yml` is in the repository root
* Verify the `rules` section matches your intended triggers
* Review **CI/CD > Pipelines** for error messages
* Validate the YAML syntax using GitLab's CI Lint tool (**CI/CD > Editor > Validate**)

## Support

* 📧 Email: [support@codeant.ai](mailto:support@codeant.ai)
* 📚 Documentation: [https://docs.codeant.ai](https://docs.codeant.ai)
* 🐛 Issues: [GitLab Issues](https://gitlab.com/codeant-pipelines/ci-scan-gitlab)
* 💬 GitLab CI/CD Docs: [https://docs.gitlab.com/ee/ci/](https://docs.gitlab.com/ee/ci/)

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## About CodeAnt

CodeAnt provides automated code analysis and security scanning to help developers build secure, high-quality software. Visit [codeant.ai](https://codeant.ai) to learn more.