> ## 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 Quality Gates in your GitHub CI Pipeline.

## CodeAnt Quality Gate Scan Action

This GitHub Action runs CodeAnt CI quality gate scan with secret detection and code quality analysis on your repository. It integrates seamlessly with your CI/CD pipeline to provide automated scanning and will fail your workflow if secrets are detected or quality gates fail.

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

### Features

* 🔒 Secret detection and security scanning
* 📊 Code quality gate enforcement
* 🚀 Fast and efficient scanning
* 🔄 Seamless CI/CD integration
* 📈 Detailed reports and insights
* ⏱️ Configurable polling and timeout
* ✅ Pass/Fail workflow status based on scan results

### Inputs

| Name            | Description                                                               | Required | Default                  |
| --------------- | ------------------------------------------------------------------------- | -------- | ------------------------ |
| `access_token`  | GitHub Personal Access Token (PAT) or repository token for authentication | Yes      | -                        |
| `api_base`      | Base URL for CodeAnt API                                                  | No       | `https://api.codeant.ai` |
| `timeout`       | Maximum time in seconds to wait for results                               | No       | `300`                    |
| `poll_interval` | Time in seconds between polling attempts                                  | No       | `15`                     |

## Setup

### 1. Get Your GitHub Access Token

* Log in to your GitHub account
* Go to **Settings** > **Developer settings** > **Personal access tokens** > **Tokens (classic)**
* Click **Generate new token (classic)**
* Select the `repo` scope
* Generate and copy the token

### 2. Add Token to GitHub Secrets

* Go to your repository's Settings
* Navigate to Secrets and variables → Actions
* Click "New repository secret"
* Name: `ACCESS_TOKEN_GITHUB`
* Value: Paste your GitHub access token
* Click "Add secret"

## Usage

### Basic Example

```yaml theme={null}
name: CODEANT QUALITY GATE SCAN

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

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Run CodeAnt Scan
        uses: CodeAnt-AI/codeant-quality-gates@v0.0.5
        with:
          access_token: ${{ secrets.ACCESS_TOKEN_GITHUB }}
```

### With Custom Configuration

```yaml theme={null}
- name: Run CodeAnt Quality Gate Scan
  uses: CodeAnt-AI/codeant-quality-gates@v0.0.5
  with:
    access_token: ${{ secrets.ACCESS_TOKEN_GITHUB }}
    api_base: https://api.codeant.ai
    timeout: 600           # Wait up to 10 minutes for results
    poll_interval: 20      # Poll every 20 seconds
```

### Complete Workflow Example

```yaml theme={null}
name: CodeAnt Quality Gate

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

jobs:
  quality-gate:
    name: Quality Gate Scan
    runs-on: ubuntu-latest
    steps:
      - name: Run CodeAnt Quality Gate Scan
        uses: CodeAnt-AI/codeant-quality-gates@v0.0.5
        with:
          access_token: ${{ secrets.ACCESS_TOKEN_GITHUB }}
          api_base: https://api.codeant.ai
          timeout: 300
          poll_interval: 15
```

## How It Works

1. **Checkout**: Checks out your repository code
2. **Fetch Script**: Downloads the quality gates scanning script from CodeAnt API
3. **Start Scan**: Initiates the quality gate scan on CodeAnt servers
4. **Poll Results**: Continuously polls for scan results until completion or timeout
5. **Report Status**: Reports pass/fail status with GitHub annotations

### Expected Output

**When Quality Gate Passes:**

> ✅ Quality Gate PASSED - No secrets detected

The workflow continues successfully.

**When Quality Gate Fails:**

> ❌ Quality Gate FAILED - Secrets detected or scan error

The workflow fails, preventing merge/deployment.

## Required Permissions

The `access_token` requires the following permissions:

* `repo` - Full control of private repositories (for reading code)
* `contents: read` - Read access to repository contents

## Quality Gate Checks

Currently, the quality gate performs the following checks:

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

## Best Practices

1. **Run on all branches**: Quality gates should run on every push to catch issues early
2. **Block merges**: Configure branch protection rules to require quality gate checks before merging
3. **Review failures**: When quality gates fail, review the detected issues immediately
4. **Keep tokens secure**: Never commit access tokens directly - always use GitHub Secrets

## Troubleshooting

### Quality gate times out

If the scan takes longer than expected:

* Increase the timeout using `timeout: 600` (10 minutes)
* Check if the CodeAnt service is operational

### Authentication failures

If you see "Access token invalid":

* Verify your `access_token` is correctly configured in GitHub Secrets
* Ensure the token has appropriate repository permissions

### No results returned

If the scan completes but returns no results:

* Check that quality gates are enabled for your repository in CodeAnt
* Verify the commit SHA is correct

## License

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

## Support

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