> ## 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.

# Github Actions

> Set up CodeAnt into your github CI Pipeline.

## CodeAnt CI Scan Action

A GitHub Action to run CodeAnt CI security and code quality analysis on your repository.

You can find this action on the [GitHub Marketplace](https://github.com/marketplace/actions/codeant-ci-scan).

### Features

* 🛡️ Automated security and code quality scanning
* 🔍 Deep code analysis and vulnerability detection
* 📊 Detailed reports and insights
* ⚡ Fast and easy integration

## Usage

### Basic Usage

Add this action to your workflow:

```yaml theme={null}
name: CodeAnt CI Scan

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  codeant_scan:
    name: Run CodeAnt CI scan
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Run CodeAnt CI Scan
        uses: CodeAnt-AI/codeant-ci-scan-action@v0.0.5
        with:
          access_token: ${{ secrets.CODEANT_TOKEN }}
```

### Advanced Usage

Customize the scan with additional options:

```yaml theme={null}
- name: Run CodeAnt CI Scan
  uses: CodeAnt-AI/codeant-ci-scan-action@v0.0.5
  with:
    access_token: ${{ secrets.CODEANT_TOKEN }}
    scanners: 'sast,sca'
    include_paths: 'src/,lib/'
    exclude_paths: 'test/,docs/'
```

## Inputs

| Input           | Description                                                                                                              | Required | Default                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------ |
| `access_token`  | CodeAnt API token (`cdt_…`) - see [API Tokens](/settings/api-tokens)                                                     | Yes      | -                        |
| `api_base`      | CodeAnt API base URL                                                                                                     | No       | `https://api.codeant.ai` |
| `scanners`      | Comma-separated list of scanners to run                                                                                  | No       | `sast,sca`               |
| `include_paths` | Comma-separated paths to include in scan                                                                                 | No       | `''` (all files)         |
| `exclude_paths` | Comma-separated paths to exclude from scan                                                                               | No       | `''` (none)              |
| `quality_gate`  | Fail the workflow if the whole-repo quality gate does not pass. Writes `results.json`, `codeant.sarif`, `codeant-qg.xml` | No       | `false`                  |

## Setup

### 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 GitHub personal access token.

### 2. Add Token to GitHub Secrets

* Go to your repository's Settings
* Navigate to Secrets and variables → Actions
* Click "New repository secret"
* Name: `CODEANT_TOKEN`
* Value: Paste your CodeAnt token (`cdt_…`)
* Click "Add secret"

### 3. Create Workflow File

Create `.github/workflows/codeant-scan.yml` in your repository with the usage example above.

## Supported Events

This action works with any GitHub event that provides commit information:

* `push`
* `pull_request`
* `workflow_dispatch`
* `schedule`

## Example Workflows

### Scan on Push and Pull Request

```yaml theme={null}
name: CodeAnt CI Scan

on:
  push:
    branches: [ "main", "develop" ]
  pull_request:
    branches: [ "main" ]

jobs:
  codeant_scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: CodeAnt-AI/codeant-ci-scan-action@v0.0.5
        with:
          access_token: ${{ secrets.CODEANT_TOKEN }}
```

### Scheduled Daily Scan

```yaml theme={null}
name: Daily CodeAnt Scan

on:
  schedule:
    - cron: '0 2 * * *'  # Run at 2 AM UTC daily

jobs:
  codeant_scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: CodeAnt-AI/codeant-ci-scan-action@v0.0.5
        with:
          access_token: ${{ secrets.CODEANT_TOKEN }}
```

### Scan Specific Directories with Security Focus

```yaml theme={null}
- uses: CodeAnt-AI/codeant-ci-scan-action@v0.0.5
  with:
    access_token: ${{ secrets.CODEANT_TOKEN }}
    scanners: 'sast,secrets'
    include_paths: 'src/,backend/'
    exclude_paths: 'src/tests/,backend/vendor/'
```

## Scanner Options

🔍 **Available Scanners:**

The `scanners` input 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'`

### Scanner Configuration Examples

#### Run All Scanners

```yaml theme={null}
- uses: CodeAnt-AI/codeant-ci-scan-action@v0.0.5
  with:
    access_token: ${{ secrets.CODEANT_TOKEN }}
    scanners: 'all'
```

#### Security-Focused Scan

```yaml theme={null}
- uses: CodeAnt-AI/codeant-ci-scan-action@v0.0.5
  with:
    access_token: ${{ secrets.CODEANT_TOKEN }}
    scanners: 'sast,secrets'
```

## Quality Gate Enforcement

🚦 **Block the workflow on the whole-repository posture:**

Set `quality_gate: true` to turn the scan into an enforced gate. After the scan completes, CodeAnt evaluates the **entire repository** against your thresholds and the workflow **fails** if the gate does not pass. This is the Checkmarx / SonarQube-style whole-repo gate, independent of the new-code/PR quality gate.

**Configure thresholds** in **Settings → Code Analysis → Quality Gates** using the **"(Full Code / CI Pipeline)"** metrics (these run only in the pipeline, never on pull requests):

* `(Full Code / CI Pipeline) SAST Security Rating` `≤` `C`
* `(Full Code / CI Pipeline) SCA Security Rating` `≤` `C`
* `(Full Code / CI Pipeline) IaC Security Rating` `≤` `C`
* `(Full Code / CI Pipeline) Duplicate Code Percentage` `>` `30`

Results group into three status checks: **SAST** (app security + IaC), **SCA** (dependencies), and **SCR** (duplicate code).

```yaml theme={null}
- name: CodeAnt Quality Gate
  uses: CodeAnt-AI/codeant-ci-scan-action@v0.0.5
  with:
    access_token: ${{ secrets.CODEANT_TOKEN }}
    scanners: 'all'
    quality_gate: true
- name: Upload CodeAnt SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: codeant.sarif
```

## Troubleshooting

### Authentication Errors

* Ensure your `CODEANT_TOKEN` is correctly set in repository secrets
* Verify the CodeAnt token (`cdt_…`) hasn't been revoked
* Check that the token belongs to the same organization as the repository

### Scan Failures

* Verify your repository is accessible
* Check that the API base URL is correct
* Review the action logs for specific error messages

## Support

* 📧 Email: [chinmay@codeant.ai](mailto:chinmay@codeant.ai)
* 📚 Documentation: [https://docs.codeant.ai](https://docs.codeant.ai)
* 🐛 Issues: [GitHub Issues](https://github.com/CodeAnt-AI/codeant-ci-scan-action/issues)

## License

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

## On-Premise Deployment

If you are using a self-hosted CodeAnt instance, you can specify a custom API endpoint using the `api_base` parameter:

```yaml theme={null}
- name: Run CodeAnt CI Scan
  uses: CodeAnt-AI/codeant-ci-scan-action@v0.0.5
  with:
    access_token: ${{ secrets.CODEANT_TOKEN }}
    api_base: 'https://your-codeant-instance.example.com'
```

> **Note:** The `api_base` parameter is only required for on-premise deployments. Cloud users do not need to configure this.

***

## Support

For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/CodeAnt-AI/codeant-ci-scan-action).

## 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](/settings/api-tokens#permissions-and-scopes).