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

# Quality Gate (GitHub Action)

> Fail CI builds when data quality drops below your threshold using the ORCA Quality Gate GitHub Action.

## Overview

The ORCA Quality Gate is a GitHub Action that runs data quality scans as part of your CI/CD pipeline. It scans a connected data source, evaluates the quality score against a configurable threshold, and posts results as a PR comment.

Use it to prevent merging code that degrades data quality.

## Quick start

Add the action to any workflow file in `.github/workflows/`:

```yaml theme={null}
name: Data Quality Check
on: [pull_request]

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: ORCA Quality Gate
        uses: klavest/orca-quality-gate@v1
        with:
          api-key: ${{ secrets.ORCA_API_KEY }}
          api-url: ${{ secrets.ORCA_API_URL }}
          source-id: "a1b2c3d4-5678-9abc-def0-1234567890ab"
```

## Inputs

| Input              | Required | Default    | Description                                    |
| ------------------ | -------- | ---------- | ---------------------------------------------- |
| `api-key`          | Yes      | --         | ORCA API key (store as a repository secret)    |
| `api-url`          | Yes      | --         | ORCA instance URL                              |
| `source-id`        | Yes      | --         | UUID of the data source to scan                |
| `table`            | No       | all tables | Specific table to scan                         |
| `min-score`        | No       | `80`       | Minimum quality score to pass (0-100)          |
| `fail-on-critical` | No       | `true`     | Fail the step if any critical alerts are found |

## Outputs

| Output          | Description                             |
| --------------- | --------------------------------------- |
| `quality-score` | The quality score from the scan (0-100) |
| `alerts-count`  | Total number of alerts found            |
| `result-url`    | Link to results in the ORCA dashboard   |

### Using outputs in subsequent steps

```yaml theme={null}
- name: ORCA Quality Gate
  id: orca
  uses: klavest/orca-quality-gate@v1
  with:
    api-key: ${{ secrets.ORCA_API_KEY }}
    api-url: ${{ secrets.ORCA_API_URL }}
    source-id: "a1b2c3d4-5678-9abc-def0-1234567890ab"

- name: Print score
  run: echo "Quality score is ${{ steps.orca.outputs.quality-score }}"
```

## PR comment

On pull request events, the action automatically posts (or updates) a comment on the PR with scan results:

```markdown theme={null}
## ORCA Quality Gate Results

| Metric | Value | Status |
|--------|-------|--------|
| Quality Score | 87/100 | [PASS] |
| Critical Alerts | 0 | [OK] |
| Warnings | 2 | [WARNING] |

### Top Issues
- `email`: 12% null rate exceeds 5% threshold
- `signup_date`: 3 rows with future dates detected

View full results in ORCA

---
Powered by ORCA | Quality threshold: 80
```

The comment is updated in place on re-runs so your PR stays clean.

## Pass/fail behavior

The action exits with code 1 (fails the step) when either condition is met:

1. **Score threshold**: Quality score is below `min-score`
2. **Critical alerts**: Any critical-severity alerts exist and `fail-on-critical` is `true`

Both conditions are evaluated independently. A scan can fail on critical alerts even if the score is above the threshold.

## Examples

### Scan a specific table

```yaml theme={null}
- name: ORCA Quality Gate
  uses: klavest/orca-quality-gate@v1
  with:
    api-key: ${{ secrets.ORCA_API_KEY }}
    api-url: ${{ secrets.ORCA_API_URL }}
    source-id: ${{ secrets.ORCA_SOURCE_ID }}
    table: "orders"
    min-score: 90
```

### Matrix strategy for multi-source scanning

Scan multiple data sources in parallel:

```yaml theme={null}
name: Data Quality
on: [pull_request]

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        source:
          - id: "src-warehouse-prod"
            name: "Warehouse"
            threshold: 85
          - id: "src-crm-prod"
            name: "CRM"
            threshold: 90
          - id: "src-events-prod"
            name: "Events"
            threshold: 75
    steps:
      - uses: actions/checkout@v4

      - name: "ORCA: ${{ matrix.source.name }}"
        uses: klavest/orca-quality-gate@v1
        with:
          api-key: ${{ secrets.ORCA_API_KEY }}
          api-url: ${{ secrets.ORCA_API_URL }}
          source-id: ${{ matrix.source.id }}
          min-score: ${{ matrix.source.threshold }}
```

### Warn without failing

Set `min-score` to `0` and `fail-on-critical` to `false` to run the scan and post the PR comment without blocking the build:

```yaml theme={null}
- name: ORCA Quality Gate (advisory)
  uses: klavest/orca-quality-gate@v1
  with:
    api-key: ${{ secrets.ORCA_API_KEY }}
    api-url: ${{ secrets.ORCA_API_URL }}
    source-id: ${{ secrets.ORCA_SOURCE_ID }}
    min-score: 0
    fail-on-critical: false
```

### Scheduled quality check

Run quality scans on a cron schedule outside of PRs:

```yaml theme={null}
name: Nightly Quality Scan
on:
  schedule:
    - cron: "0 6 * * *"

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: ORCA Quality Gate
        uses: klavest/orca-quality-gate@v1
        with:
          api-key: ${{ secrets.ORCA_API_KEY }}
          api-url: ${{ secrets.ORCA_API_URL }}
          source-id: ${{ secrets.ORCA_SOURCE_ID }}
          min-score: 80
```

## How it works

1. Sets up Python 3.11 and installs `orca-cli`
2. Runs `orca scan --wait --format json` against the specified source
3. Parses the JSON output to extract the quality score and alerts
4. Sets GitHub Action outputs (`quality-score`, `alerts-count`, `result-url`)
5. On pull request events, posts or updates a Markdown comment on the PR
6. Exits with code 0 (pass) or 1 (fail) based on thresholds

## Secrets setup

Store your ORCA credentials as GitHub repository secrets:

1. Go to **Settings > Secrets and variables > Actions**
2. Add `ORCA_API_KEY` with your ORCA API key
3. Add `ORCA_API_URL` with your ORCA instance URL (e.g. `https://api.orca-klavest.app`)
4. Optionally add `ORCA_SOURCE_ID` if you want to reference it as a secret