> ## 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](https://docs.codeant.ai/settings/api-tokens.md) | 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`).

## Usage

### Quick Start (Recommended)

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

```yaml .gitlab-ci.yml theme={"theme":"css-variables"}
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 .gitlab-ci.yml theme={"theme":"css-variables"}
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 .gitlab-ci.yml expandable theme={"theme":"css-variables"}
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, go to **Settings → API Tokens**, click **Create token**, and copy the generated token (it starts with `cdt_` and is shown only once). See [API Tokens](https://docs.codeant.ai/settings/api-tokens.md) 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={"theme":"css-variables"}
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={"theme":"css-variables"}
   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 - All enabled checks passed
```

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 - One or more enabled checks failed
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 .gitlab-ci.yml theme={"theme":"css-variables"}
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 .gitlab-ci.yml theme={"theme":"css-variables"}
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 .gitlab-ci.yml theme={"theme":"css-variables"}
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
* Compare the masked token shown in the job log (for example, `cdt_********a1b2`) with the token you intended to use. The script prints only the first and last four characters and never prints the complete token.
* **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. `403` authorization failure**

* The token was recognized but lacks either repository access or the required **Codeant CI/CD** permission
* Update the token's role or repository scope in CodeAnt, then rerun the job

**4. "Timeout waiting for results"**

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

**5. 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

### Built-in diagnostics

The quality gate script automatically logs the masked token identity, service, repository, and provider base URL. These values are safe to share with support and are usually enough to distinguish an expired token from a repository or self-hosted URL mismatch.

Do not echo `ACCESS_TOKEN` or enable `set -x`; shell tracing can expose secret arguments on some runners.

## Advanced Usage

### Multiple Quality Gates

Run different quality gates for different branches:

```yaml .gitlab-ci.yml theme={"theme":"css-variables"}
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 .gitlab-ci.yml expandable theme={"theme":"css-variables"}
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/index.md)
* **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## Token permission

This pipeline authenticates with a CodeAnt API token (`cdt_…`). If the token is **scoped**, give it the **Codeant CI/CD** role - it covers scans, quality gates, and test-coverage upload - scoped to the repositories this pipeline runs on (or **All repositories**). A token missing the required permission is rejected with an HTTP `403` `token_scope_forbidden` error that names the permission it needs. See [API token permissions](https://docs.codeant.ai/settings/api-tokens.md#permissions-and-scopes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.