# Gatekeep

AI-assisted PR review for **your own repos**: parallel multi-model review across **providers**, fail-closed PR risk tiers, agreed-only inline findings, blocking security check.

**中文说明：** [README.zh-CN.md](./README.zh-CN.md)

## Install (remote `uses:`)

```yaml
# .github/workflows/gatekeep.yml  ← must live under .github/workflows/ on Gitea/GitHub
- uses: actions/checkout@v4
- uses: https://git.potatolab.uk/layue13/gatekeep@main
  # placeholder: uses: https://git.example.com/OWNER/gatekeep@v1
  env:
    # Names must match providers.yaml `key` — FREE-FORM (no required gatekeep_ prefix)
    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
```

### Dogfood (this repo)

`layue13/gatekeep` reviews **its own** PRs via [`.github/workflows/gatekeep-pr.yml`](.github/workflows/gatekeep-pr.yml) with `uses: ./` and `secrets.OPENROUTER_API_KEY`. Open a PR against `main` to see a review (Gitea Actions must have a runner — same pool as other `layue13` repos).

Because dogfood uses `uses: ./`, **rebase/merge `main` into the PR branch** after Action fixes land, or the PR still runs the old Action. Re-run via new push or **Actions → Gatekeep → Run workflow**. Free-model 429s are retried; extras in `models:` after the first 3 are fallbacks; risk is force-high only if **zero** models succeed.

Allowlists / Gitea-on-github.com limitations: [`docs/remote-uses.md`](docs/remote-uses.md).

## Providers YAML

```yaml
language: zh-CN               # report language: zh-CN | en | … (prompts + published comments)

providers:
  openrouter:                 # only include providers you configure
    key: OPENROUTER_API_KEY   # free-form secret/env name — pick any
    protocol: openai          # openai | openai-completions | openai-responses | anthropic
    # base_url: optional (defaults exist for openrouter / anthropic / openai)
    models:
      - cohere/north-mini-code:free
      - nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free
      - google/gemma-4-31b-it:free
```

| Field | Meaning |
| --- | --- |
| `language` | Report language for model prose + summary/inline comments (`zh-CN`, `en`, …). Alias: `report_language`. |
| `key` | **Free-form** name of the GitHub secret / env var holding the API key. **No** required `gatekeep_` prefix. |
| `protocol` | `openai` \| `openai-completions` \| `openai-responses` \| `anthropic` |
| `models` | Names to use (validated against the provider’s model list API at runtime) |
| `base_url` | Optional; known provider ids get defaults |

### Report language

- **This repo’s defaults:** `language: zh-CN` in `defaults/providers.yaml`.
- **Override without editing YAML:** Action input `language: en` (or `zh-CN`).
- Resolution order: Action input `language` → YAML `language` / `report_language` → `en`.
- JSON field names and enums stay English; human-facing prose follows the configured language.

Mix providers in one review by listing several entries. Secrets are read from the **workflow step `env`** using each entry’s `key` name.

Example suggestion only (still free-form): `key: gatekeep_openrouter` is fine if you named your secret that — not required.

## Finding format

**Severity** (Critical→Low) + **where** (`path:line`) + **why it matters**. Inline only when ≥2 models agree.

## PR risk tiers

| Tier | Humans | Auto-merge |
| --- | --- | --- |
| low | 0 after Gatekeep + security green | If kill switch on |
| medium | 1 | No |
| high | 2 | No |

## Optional consumer config

`config-dir: .github/gatekeep` with your `providers.yaml`. Omit to use Action `defaults/providers.yaml`.

## Layout

```
action.yml
scripts/            # resolve-providers.py, call-model.sh, …
defaults/providers.yaml
config/providers.yaml   # example override
workflows/  templates/  evals/  incidents/  docs/
```