> ## 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 CI/CD

> Set up CodeAnt Quality Gates in your GitLab CI Pipeline.

# CodeAnt Quality Gate Scan for GitLab

This GitLab CI/CD pipeline runs CodeAnt quality gate scan with secret detection and code quality analysis. It integrates with your CI/CD pipeline and fails if secrets are detected or quality gates fail.

## Features

* 🔒 Secret detection and security scanning
* 📊 Code quality gate enforcement
* ⏱️ Configurable polling and timeout
* ✅ Pass/Fail pipeline status based on scan results

## Variables

| Name           | Description                                                                                                                                                                                                   | Required | Default                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------ |
| ACCESS\_TOKEN  | CodeAnt API token (`cdt_…`) for authentication — see [API Tokens](/settings/api-tokens)                                                                                                                       | Yes      | -                                                |
| API\_BASE      | Base URL for CodeAnt API                                                                                                                                                                                      | No       | [https://api.codeant.ai](https://api.codeant.ai) |
| BASE\_URL      | Base URL of your GitLab instance. Defaults to the predefined `CI_SERVER_URL`, which is correct for both GitLab SaaS and self-hosted. Override only if your runner reports a different URL than your instance. | No       | \$CI\_SERVER\_URL                                |
| TIMEOUT        | Maximum time in seconds to wait for results                                                                                                                                                                   | No       | 300                                              |
| POLL\_INTERVAL | Time in seconds between polling attempts                                                                                                                                                                      | No       | 15                                               |

<Note>
  **Self-hosted GitLab:** The pipeline forwards your instance URL (`CI_SERVER_URL`) to CodeAnt so the token is validated against the correct GitLab server. This happens automatically — no extra configuration is needed. If validation fails with `401 Access token invalid`, confirm `CI_SERVER_URL` resolves to your GitLab instance, or set `BASE_URL` explicitly (e.g. `https://gitlab.your-company.com`).
</Note>

## Usage

### Quick Start (Recommended)

Add this to your `.gitlab-ci.yml`:

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

stages:
  - quality-gate

codeant-quality-gate:
  variables:
    API_BASE: "https://api.codeant.ai"
    TIMEOUT: "600"           # Wait up to 10 minutes for results
    POLL_INTERVAL: "20"      # Poll every 20 seconds
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

Set the `ACCESS_TOKEN` variable in your GitLab project settings (**Settings > CI/CD > Variables**).

### With Custom Job Name

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

codeant-scan:
  extends: .codeant-quality-gate
  stage: quality-gate
  variables:
    TIMEOUT: "600"
    POLL_INTERVAL: "20"
```

### With Multiple Stages

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

stages:
  - build
  - quality-gate
  - deploy

build:
  stage: build
  script:
    - echo "Building..."

codeant-quality-gate:
  variables:
    TIMEOUT: "600"

deploy:
  stage: deploy
  script:
    - echo "Deploying..."
  only:
    - main
```

## Setup Instructions

### Step 1: Create a CodeAnt Token

In CodeAnt AI, open the user menu (click your email at the bottom-left) and select **API Tokens**, click **Create token**, and copy the generated token (it starts with `cdt_` and is shown only once). See [API Tokens](/settings/api-tokens) for the full walkthrough. This single token authenticates the scan — you don't need a GitLab access token.

### Step 2: Add Pipeline Configuration

Copy the `.gitlab-ci.yml` file from this repository to the root of your GitLab project.

### Step 3: Configure CI/CD Variables

Add the required `ACCESS_TOKEN` variable to your GitLab project:

1. Go to **Settings > CI/CD > Variables**
2. Click **Add Variable**
3. Configure:
   * **Key:** `ACCESS_TOKEN` (this is the variable name the included template reads)
   * **Value:** Your CodeAnt token (`cdt_…`)
   * **Type:** Variable
   * **Environment scope:** All
   * **Protect variable:** ✓ (Recommended)
   * **Mask variable:** ✓ (Recommended)
4. Click **Add variable**

### Step 4: Commit and Push

```bash theme={null}
git add .gitlab-ci.yml
git commit -m "Add CodeAnt quality gate pipeline"
git push origin main
```

The pipeline will automatically run on the next merge request or commit to the main branch.

## Testing from Another Repository

To test this pipeline configuration in your own repository:

1. Clone or copy the `.gitlab-ci.yml` to your repository
2. Set up the `ACCESS_TOKEN` variable in your project settings
3. Push to trigger the pipeline:
   ```bash theme={null}
   git push origin feature-branch
   ```
4. Create a merge request to test automatic scanning

For testing specific configurations:

* Modify the `variables` section in `.gitlab-ci.yml`
* Add custom rules for when the pipeline should run
* Adjust timeout and polling intervals as needed

## How It Works

1. **Checkout:** GitLab automatically checks out your repository code
2. **Fetch Script:** Downloads the quality gates scanning script from CodeAnt API
3. **Prepare Script:** Decodes and prepares the script for execution
4. **Start Scan:** Initiates the quality gate scan on CodeAnt servers
5. **Poll Results:** Continuously polls for scan results until completion or timeout
6. **Report Status:** Reports pass/fail status and fails the pipeline if issues are detected

## Expected Output

### When Quality Gate Passes:

```
Fetching quality gates script from https://api.codeant.ai...
Successfully fetched quality gates script
Quality gates script prepared successfully
Starting quality gate scan...
Quality gate scan initiated successfully
Polling for quality gate results...
Quality gate results retrieved successfully
✅ Quality Gate PASSED - No secrets detected
```

The pipeline succeeds and allows merge/deployment to proceed.

### When Quality Gate Fails:

```
Starting quality gate scan...
Polling for quality gate results...
❌ Quality Gate FAILED - Secrets detected or scan error
Job failed: exit code 1
```

The pipeline fails, preventing merge/deployment and requiring fixes.

## Quality Gate Checks

The quality gate performs comprehensive checks including:

### Security and Code Quality Checks

* **Secret Detection**: Scans for hardcoded secrets, API keys, passwords, and tokens
* **SAST (Static Application Security Testing)**: Detects security vulnerabilities in source code
* **SCA (Software Composition Analysis)**: Identifies vulnerabilities in third-party dependencies
* **IaC (Infrastructure as Code)**: Scans infrastructure configuration files for security issues
* **Duplicate Code Detection**: Identifies code duplication to improve maintainability
* Analyzes only the changed lines since your merge base commit
* Uses high-confidence detection to minimize false positives
* Blocks the build if any issues are found

## GitLab CI/CD Variables Used

The pipeline automatically uses these GitLab-provided variables:

| Variable               | Description                                                 |
| ---------------------- | ----------------------------------------------------------- |
| \$CI\_PROJECT\_PATH    | Project path (e.g., codeant-pipelines/quality-gates-gitlab) |
| \$CI\_COMMIT\_SHA      | Current commit SHA                                          |
| \$CI\_DEFAULT\_BRANCH  | Default branch name (usually main or master)                |
| \$CI\_PIPELINE\_SOURCE | Source that triggered the pipeline                          |
| \$CI\_COMMIT\_BRANCH   | Current branch name                                         |
| \$CI\_JOB\_STATUS      | Job status (success/failed)                                 |

## Configuration Options

### Variables

Customize these variables in `.gitlab-ci.yml`:

```yaml theme={null}
variables:
  API_BASE: "https://api.codeant.ai"      # CodeAnt API endpoint
  BASE_URL: "$CI_SERVER_URL"              # GitLab instance URL (auto for SaaS & self-hosted)
  TIMEOUT: "300"                          # Scan timeout in seconds
  POLL_INTERVAL: "15"                     # Polling interval in seconds
```

### Pipeline Rules

Control when the pipeline runs:

```yaml theme={null}
rules:
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"  # Run on MRs
  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH       # Run on main branch
  - if: $CI_COMMIT_BRANCH                              # Manual run on any branch
    when: manual
```

### Allow Failure

To make the quality gate advisory (non-blocking):

```yaml theme={null}
codeant-quality-gate:
  allow_failure: true  # Pipeline continues even if quality gate fails
```

## Troubleshooting

### Common Issues

**1. "Failed to fetch quality gates script"**

* Verify `API_BASE` URL is correct
* Check network connectivity from GitLab runners to CodeAnt API
* Ensure API endpoint is accessible

**2. "Authentication failed" / `401 Access token invalid`**

* Verify `ACCESS_TOKEN` holds a valid CodeAnt token (`cdt_…`) that hasn't been revoked
* Ensure the token belongs to the same organization as the repository
* **Self-hosted GitLab:** the token is validated against the GitLab instance reported by `BASE_URL` (default `$CI_SERVER_URL`). A 401 usually means CodeAnt validated against the wrong instance — confirm `CI_SERVER_URL` points to your GitLab server, or set `BASE_URL` explicitly (e.g. `https://gitlab.your-company.com`)

**3. "Timeout waiting for results"**

* Increase `TIMEOUT` value for larger repositories
* Check CodeAnt API status
* Review scan logs for errors

**4. Pipeline doesn't run automatically**

* Verify `.gitlab-ci.yml` is in repository root
* Check CI/CD is enabled for the project
* Review pipeline rules configuration

### Debug Mode

To enable detailed logging, add debug commands:

```yaml theme={null}
script:
  - set -x  # Enable debug output
  - echo "DEBUG: API_BASE=${API_BASE}"
  - echo "DEBUG: CI_PROJECT_PATH=${CI_PROJECT_PATH}"
  - echo "DEBUG: CI_COMMIT_SHA=${CI_COMMIT_SHA}"
```

## Advanced Usage

### Multiple Quality Gates

Run different quality gates for different branches:

```yaml theme={null}
quality-gate-strict:
  extends: .codeant-quality-gate
  variables:
    TIMEOUT: "600"
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

quality-gate-advisory:
  extends: .codeant-quality-gate
  allow_failure: true
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
```

### Integration with Other Jobs

Chain the quality gate with other jobs:

```yaml theme={null}
stages:
  - quality-gate
  - test
  - deploy

codeant-quality-gate:
  stage: quality-gate
  # ... configuration ...

unit-tests:
  stage: test
  needs: ["codeant-quality-gate"]  # Wait for quality gate
  script:
    - npm test

deploy:
  stage: deploy
  needs: ["codeant-quality-gate", "unit-tests"]
  script:
    - ./deploy.sh
  only:
    - main
```

## Support

For issues, questions, or contributions, please:

* **Documentation:** [https://docs.codeant.ai](https://docs.codeant.ai)
* **GitLab CI/CD:** [https://docs.gitlab.com/ee/ci/](https://docs.gitlab.com/ee/ci/)
* **Issues:** Contact your CodeAnt support team or create an issue in this repository

## License

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

**Repository:** [https://gitlab.com/codeant-pipelines/quality-gates-gitlab](https://gitlab.com/codeant-pipelines/quality-gates-gitlab)

**Powered by CodeAnt AI** - Automated Code Quality and Security Analysis