# OpenCodeReview (`ocr`) — why this repo has no review workflow yet

> **Status: not adopted as CI.** There is no OpenCodeReview workflow in this
> repository, so there is no `workflow_dispatch` trigger to add and no SARIF
> upload to wire. This file records the decision, the blocker, and the exact
> enablement path if the Owner decides to adopt it.

## What OpenCodeReview is

[`alibaba/open-code-review`](https://github.com/alibaba/open-code-review) is an
Apache-2.0 code-review CLI (`ocr`) with a deterministic selection/rule layer and
an LLM review layer. It reads a Git diff (`ocr review`), a commit, a branch
range, or whole files (`ocr scan`) and can emit `text`, `json`, or **`sarif`**.

Two properties matter for CI:

- **It is advisory, not a gate.** The CLI has no `fail_on_severity`; findings do
  not make it exit non-zero. `--max-tokens-budget` explicitly publishes partial
  results and exits 0; it exits non-zero only when every selected item failed.
- **The SARIF upload is free; the review that fills it is not.** `--preview` and
  `ocr delegate preview` are deterministic and need no LLM, but they only list
  the files that *would* be reviewed — `delegate` explicitly does not support
  SARIF. Producing findings (and therefore SARIF) requires a configured provider
  and a token.

The 2026-10-22 SEC audit recommended a phased, advisory-only adoption and
explicitly said not to put OCR on the merge path. This file implements the
"otherwise document why not" half of that follow-up.

## Why no workflow was added

1. **There is nothing to add a trigger to.** `git ls-files .github/workflows`
   lists five files — `banner.yml`, `baseline-audit.yml`, `ci.yml`,
   `release.yml`, `star-history.yml` — and none of them runs OCR.
2. **A SARIF-producing review needs an LLM credential.** `ocr review --format
   sarif` calls the configured provider. Without a provider token the command
   cannot produce findings; a SARIF file with no findings is not a review.
3. **This repository has zero Actions secrets.** Checked 2026-10-23:
   `gh api repos/dwgx/WindsurfAPI/actions/secrets --jq .total_count` → `0`.
   Adding a review job that expects `OCR_LLM_TOKEN` would add a secret the repo
   does not have, which is exactly the condition the follow-up excludes. The
   upstream example workflow
   (`alibaba/open-code-review/.github/workflows/ocr-review.yml`) is a
   `pull_request_target` job on a `self-hosted` runner with
   `pull-requests: write`, and it maps four secrets (`OCR_LLM_URL`,
   `OCR_LLM_AUTH_TOKEN`, `OCR_LLM_MODEL`, `OCR_LLM_USE_ANTHROPIC`). Copying it
   would add both the secrets and a write-scoped PR job; neither is acceptable
   without an explicit decision.
4. **The SARIF upload itself is not the blocker.** `security-events: write` is a
   workflow permission, not a secret, and `github/codeql-action/upload-sarif`
   needs nothing else. The blocker is the review that fills the file.
5. **`GITHUB_TOKEN` + GitHub Models is technically a no-new-secret path, but it
   is not a drop-in.** GitHub Models accepts the Actions token with `models:
   read` (GitHub announced this in April 2025), so a workflow could point
   `OCR_LLM_URL` at `https://models.github.ai/inference` and use
   `${{ github.token }}`. Before adopting it we would need to verify, on a real
   dispatch: that the chosen model supports the tool-calling loop OCR uses, what
   the per-account request quota does to a multi-group review, and whether the
   output precision survives. Those are `[UNVERIFIED]`; committing an unrun job
   would be a workflow-shaped claim, not a review.
6. **OCR is non-deterministic and advisory.** The merge condition in this repo
   is the deterministic gate (`npm run gate` / CI). A second, LLM-based opinion
   belongs on a manual trigger at most, never on `pull_request`.

## Enablement path (when the Owner decides)

### Step 1 — trial before wiring anything

```bash
# free: selection only, no LLM, no network
npx --yes @alibaba-group/open-code-review@1.13.3 review --preview \
  --from origin/master --to HEAD

# one real review against a provider; measure tokens and triage precision
npx --yes @alibaba-group/open-code-review@1.13.3 review \
  --from origin/master --to HEAD --format json --output /tmp/ocr.json
```

Compare the selected-file list with what you would review by hand, then triage
the findings. The audit's rule of thumb: if precision is below roughly 50 %,
skip the integration — triaging false positives costs more than the review
saves. The audit also measured the deterministic half: a release-sized range
(`v3.9.38..v3.9.52`, 327 changed files) selected 113 files in 8.8 s, and a
typical code commit selected 1–3.

### Step 2 — add the credential (this is the step that fails today)

Add one repository secret for the provider token (name it `OCR_LLM_TOKEN`), and
repository variables for the endpoint and model (`OCR_LLM_URL`,
`OCR_LLM_MODEL`) so they are visible without opening the secret. If the provider
is this project's own gateway, the token is a gateway API key; the endpoint is
`http://<gateway>/v1` and the protocol is `openai`.

Set `OCR_ENABLE_TELEMETRY=0` in CI. The CLI reads it from the environment; it is
not a secret.

### Step 3 — commit a `workflow_dispatch`-only job

The workflow below is deliberately **not** committed by this change: it cannot
run until Step 2 exists, and an unrun workflow is not evidence. It is the exact
file to add when it can run.

```yaml
name: OpenCodeReview (manual, advisory)

on:
  workflow_dispatch:
    inputs:
      base:
        description: Base ref to diff from (for example master)
        required: true
        default: master
      head:
        description: Head ref or commit SHA to review
        required: true
      model:
        description: Provider model name (must support tool calling)
        required: false
        default: ''

permissions:
  contents: read
  security-events: write   # SARIF upload only; no pull-requests: write

concurrency:
  group: opencode-review-${{ github.ref }}
  cancel-in-progress: false

jobs:
  ocr:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: Checkout the reviewed ref
        uses: actions/checkout@v5
        with:
          ref: ${{ inputs.head }}
          fetch-depth: 0

      - name: Make the base ref available
        run: git fetch --no-tags origin "+refs/heads/${{ inputs.base }}:refs/remotes/origin/${{ inputs.base }}"

      - uses: actions/setup-node@v5
        with:
          node-version: '24'

      - name: Run OpenCodeReview (SARIF, advisory)
        env:
          OCR_LLM_URL: ${{ vars.OCR_LLM_URL }}
          OCR_LLM_MODEL: ${{ inputs.model || vars.OCR_LLM_MODEL }}
          OCR_LLM_PROTOCOL: openai
          OCR_LLM_TOKEN: ${{ secrets.OCR_LLM_TOKEN }}
          OCR_ENABLE_TELEMETRY: '0'
        run: |
          npx --yes @alibaba-group/open-code-review@1.13.3 review \
            --from "origin/${{ inputs.base }}" \
            --to HEAD \
            --format sarif \
            --output ocr.sarif \
            --audience agent

      - name: Upload SARIF
        if: always() && hashFiles('ocr.sarif') != ''
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ocr.sarif
          category: opencodereview
```

Notes on the template:

- `workflow_dispatch` only; there is no `pull_request` trigger, so a review can
  never block or annotate a PR automatically.
- `security-events: write` is required by `upload-sarif`. `pull-requests: write`
  is intentionally absent: the CLI writes a file, it does not post comments. The
  upstream action (which posts inline comments and a sticky summary) would need
  PR write scope — do not use it for a SARIF-only job.
- Pin `@alibaba-group/open-code-review@1.13.3` exactly; `npx --yes` is only a
  convenience for a manual job. Pin the actions to commit SHAs when committing
  (SEC-11), even though the surrounding workflows still use major tags.
- The job uploads an artifact-free SARIF; the file is the evidence. Add
  `actions/upload-artifact` if the raw SARIF should be kept after the code
  scanning retention window.

### Step 4 — pin and review manually

Pin the CLI version, keep the trigger manual, and triage findings as a second
reader. Do not add a wrapper that turns SARIF counts into a non-zero exit: the
review is non-deterministic, so such a wrapper would be a flaky gate.

## Zero-new-secret variant (not recommended yet)

If a no-secret trial is required, the same job can use the Actions token with
GitHub Models:

```yaml
permissions:
  contents: read
  security-events: write
  models: read

env:
  OCR_LLM_URL: https://models.github.ai/inference
  OCR_LLM_TOKEN: ${{ github.token }}
  OCR_LLM_MODEL: openai/gpt-4.1
  OCR_LLM_PROTOCOL: openai
```

Why it is not the default: it introduces a new inference dependency and a new
data flow (the diff leaves the runner for GitHub Models), the per-account
request quota is documented but has not been measured against OCR's multi-group
review, and the model's tool-calling compatibility with OCR is `[UNVERIFIED]`.
The repository is public, so source confidentiality is not the concern;
reliability and review quality are.

## Security notes

- Never run OCR on `pull_request_target` with secrets. The upstream action's
  example does that because it does not execute PR code; this repository builds
  artifacts, so that pattern does not transfer.
- A SARIF-only job needs no PR write scope and no `contents: write`.
- OCR sends the diff to the configured provider. Set `OCR_ENABLE_TELEMETRY=0`
  and point the provider at a gateway you control if that matters.
- The CLI is a Go binary downloaded by the npm wrapper at install time; pin the
  npm version and, if you need stronger supply-chain guarantees, verify the
  platform binary's checksum against the upstream release before running it.