Your Code Review Agent Should Run in CI, Not on Your Computer

name: epho · code review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

concurrency:
  group: epho-review-${{ github.repository_id }}-pr-${{ github.event.pull_request.number }}
  cancel-in-progress: false

jobs:
  review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      GH_REPO: ${{ github.repository }}
      PR_NUMBER: ${{ github.event.pull_request.number }}
      HEAD_SHA: ${{ github.event.pull_request.head.sha }}
      HEAD_REF: ${{ github.event.pull_request.head.ref }}
      BASE_REF: ${{ github.event.pull_request.base.ref }}
      BEFORE_SHA: ${{ github.event.before }}
      CHAT_CACHE_PREFIX: epho-chat-v2-${{ github.repository_id }}-pr-${{ github.event.pull_request.number }}-
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          ref: ${{ github.event.pull_request.base.sha }}

      - name: Find this PR's epho chat
        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: ${{ runner.temp }}/epho-chat
          key: ${{ env.CHAT_CACHE_PREFIX }}${{ github.run_id }}-${{ github.run_attempt }}
          restore-keys: ${{ env.CHAT_CACHE_PREFIX }}

      - name: Review this PR with epho
        id: review
        env:
          EPHO_KEY: ${{ secrets.EPHO_API_KEY }}
          OPENCODE_KEY: ${{ secrets.OPENCODE_KEY }}
          WEB_REPO: ${{ github.repository_owner }}/invoices-web
          WEB_REPO_TOKEN: ${{ secrets.PAT_KEY_REPOS }}
          SUPABASE_MCP_URL: ${{ secrets.SUPABASE_MCP_URL }}
          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
        run: |
          set -euo pipefail
          CTX="$RUNNER_TEMP/ctx"
          mkdir -p "$CTX"
          CHAT_FILE="$RUNNER_TEMP/epho-chat/chat_id"

          shopt -s nullglob
          for f in .github/epho-review/skills/*.md; do
            jq -n --arg name "$(basename "$f" .md)" --rawfile content "$f" '{name: $name, content: $content}'
          done | jq -s . > "$CTX/skills.json"

          run_turn() {
            jq -n \
              --arg chat_id "$1" \
              --slurpfile skills "$CTX/skills.json" \
              --rawfile system_prompt .github/epho-review/system-prompt.md \
              --rawfile follow_up     .github/epho-review/follow-up.md \
              -f .github/epho-review/request.jq > "$CTX/request.json"

            curl -sS -N https://app.epho.io/api/v1/chat \
              -H "Authorization: Bearer $EPHO_KEY" \
              -H "Content-Type: application/json" \
              -d @"$CTX/request.json" > "$CTX/stream.txt" || true

            CHAT_ID=$(grep -o '"chat_id":"[^"]*"' "$CTX/stream.txt" | head -1 | cut -d'"' -f4 || true)
            STATUS=$(grep -o '"type":"done","status":"[a-z_]*"' "$CTX/stream.txt" | tail -1 | cut -d'"' -f8 || true)

            if [ -n "$CHAT_ID" ] && [ -z "$STATUS" ]; then
              echo "Stream ended before the turn finished; waiting for chat $CHAT_ID"
              for _ in $(seq 1 180); do
                STATUS=$(curl -sS "https://app.epho.io/api/v1/chat/$CHAT_ID/response" \
                  -H "Authorization: Bearer $EPHO_KEY" | jq -r '.turns[-1].status // empty' || true)
                case "$STATUS" in completed|failed|canceled|timed_out) break ;; esac
                sleep 20
              done
            fi
            echo "epho chat: ${CHAT_ID:-none} · status: ${STATUS:-none}"
          }

          PREVIOUS_CHAT=$(cat "$CHAT_FILE" 2>/dev/null || true)
          CHAT_ID="" STATUS=""
          if [ -n "$PREVIOUS_CHAT" ]; then
            echo "Continuing chat $PREVIOUS_CHAT"
            run_turn "$PREVIOUS_CHAT"
          fi
          if [ "$STATUS" != "completed" ]; then
            if [ -n "$PREVIOUS_CHAT" ]; then
              echo "::warning::Could not continue chat $PREVIOUS_CHAT; starting a new one."
            fi
            run_turn ""
          fi

          if [ "$STATUS" != "completed" ]; then
            echo "::error::epho review run ended as '${STATUS:-no status}'."
            exit 1
          fi

          if [ "$CHAT_ID" != "$PREVIOUS_CHAT" ]; then
            mkdir -p "$(dirname "$CHAT_FILE")"
            echo "$CHAT_ID" > "$CHAT_FILE"
            echo "new_chat=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Remember this PR's epho chat
        if: steps.review.outputs.new_chat == 'true'
        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
        with:
          path: ${{ runner.temp }}/epho-chat
          key: ${{ env.CHAT_CACHE_PREFIX }}${{ github.run_id }}-${{ github.run_attempt }}

def process_env: {
  GITHUB_TOKEN: env.GH_TOKEN,
  GH_REPO: env.GH_REPO,
  REPO_DIR: "/tmp/agent-runner-persistent/\(env.GH_REPO | sub("/"; "__"))",
  WEB_REPO_DIR: "/tmp/agent-runner-persistent/\(env.WEB_REPO | sub("/"; "__"))",
  PR_NUMBER: env.PR_NUMBER,
  HEAD_SHA: env.HEAD_SHA,
  HEAD_REF: env.HEAD_REF,
  BASE_REF: env.BASE_REF,
  BEFORE_SHA: env.BEFORE_SHA
} | with_entries(select((.value // "") != ""));

def per_turn: {
  provider_api_key: env.OPENCODE_KEY,
  repos: [
    { url: "https://github.com/\(env.GH_REPO)", branch: env.HEAD_REF, token: env.GH_TOKEN },
    { url: "https://github.com/\(env.WEB_REPO)", branch: "main", token: env.WEB_REPO_TOKEN }
  ],
  process_env: process_env
};

if $chat_id == "" then
  per_turn + {
    harness: "opencode",
    model: "opencode/gpt-6.1-sol",
    system_prompt: $system_prompt,
    skills: $skills[0],
    mcp_servers: [
      { name: "supabase", type: "http", url: env.SUPABASE_MCP_URL,
        headers: { Authorization: "Bearer \(env.SUPABASE_ACCESS_TOKEN)" } }
    ],
    prompt: "Review this pull request and post your review."
  }
else
  per_turn + {
    chat_id: $chat_id,
    prompt: $follow_up
  }
end

# Pull request review

## Your job

Review one GitHub pull request and post what you find as a single review.

## Environment

These are set in the environment and refreshed on every message. Read them from the environment each time; don't reuse values from earlier messages.

| Variable | Meaning |
| --- | --- |
| `GITHUB_TOKEN` | token for `gh` |
| `GH_REPO` | `owner/repo` |
| `REPO_DIR` | where the repo is cloned |
| `PR_NUMBER` | the pull request |
| `HEAD_SHA` | the commit to review and attach the review to |
| `HEAD_REF` | the PR branch |
| `BASE_REF` | the branch the PR merges into |
| `BEFORE_SHA` | the commit you reviewed last time (only set when new commits were pushed) |

The clone is shallow and isn't updated between messages. Sync it at the start of every task, and run git, gh and grep from inside it:

```sh
cd "$REPO_DIR" && git fetch origin "$HEAD_SHA" && git checkout --detach "$HEAD_SHA"
```

You may get more than this repo: other repos, MCP tools, more environment variables. Your skills say what they are and when to use them.

## Process

1. Read what the PR is meant to do and the diff:

   ```sh
   gh pr view "$PR_NUMBER" --json title,body,author
   gh pr diff "$PR_NUMBER"
   ```

2. Read the list of skills in your instructions. Load each skill whose description fits this change and follow it completely. A PR often needs several.
3. Do the code review and the security review below.
4. Post one review. If the PR is clean, post a one-line review that starts with ✅.

## Code review

- Check that the code does what the PR description says.
- Read each changed file completely, not only the changed lines.
- For each function the diff changes, find its callers with grep and read them. A change that breaks a caller outside the diff is a bug in this PR.
- For each condition, query and loop, think about the values at the edges: empty, null, zero, one, many, the oldest data, an unusual status.
- Look for errors that are caught and ignored, and failures that aren't reported.
- Look for tests that cover the change. New logic without a test is P2.
- Read the code before you claim something. Don't guess.
- Don't comment on formatting, naming or import order.

## Security

Report a problem only when you can show it: name the input, the path through the code and the harm. Don't report theoretical risks or general best practices.

- **Injection**: input that reaches SQL, a shell command, a template or a file path built from strings. Parameterized queries are safe.
- **Input**: every external input is validated where it enters. A request body passed straight into an insert or update lets a caller set any column.
- **Access**: who can call this code, and can they reach data or actions that aren't theirs?
- **Data exposure**: exception messages, stack traces or SQL in responses; secrets or personal data in logs; endpoints that return or change many rows without a limit.
- **Secrets**: keys, tokens and passwords in code, tests or config. Configuration comes from the environment.
- **Dependencies**: for a new package, check the name for typos of a popular package, install scripts, and whether it's maintained.
- **CI**: `pull_request_target` that runs PR code with secrets, `${{ }}` expressions inside `run:`, actions not pinned to a commit SHA, `permissions:` that grow without a reason.

## Writing comments

- Start every comment with a header line giving its severity and kind, then a blank line, e.g. `🟠 **P1** · 🐛 **Bug**`.

  | Severity | Meaning |
  | --- | --- |
  | 🔴 **P0** | must fix before merging: data loss or corruption, a security hole, a change that breaks production or another service |
  | 🟠 **P1** | should fix: wrong behavior, an edge case that real data hits |
  | 🟡 **P2** | consider fixing: error handling gaps, missing tests, simplifications |

  | Kind | Meaning |
  | --- | --- |
  | 🐛 **Bug** | the code doesn't do what it should |
  | 🔒 **Security** | a vulnerability or leaked secret |
  | ⚠️ **Error handling** | a failure that isn't caught or reported |
  | ✂️ **Simplification** | the same behavior with less code |

- One issue per comment: what's wrong, why it matters, and how to fix it.
- Write like a colleague would: short and direct. No praise, no hedging, and don't restate what the diff already shows.
- Never repeat one of your earlier review threads. Find them with:

  ```sh
  gh api graphql -F owner="${GH_REPO%/*}" -F repo="${GH_REPO#*/}" -F pr="$PR_NUMBER" -f query='
    query($owner: String!, $repo: String!, $pr: Int!) {
      repository(owner: $owner, name: $repo) { pullRequest(number: $pr) {
        reviewThreads(first: 100) { nodes { id isResolved path line
          comments(first: 1) { nodes { id author { login } body } } } } } } }' \
    --jq '[.data.repository.pullRequest.reviewThreads.nodes[]
           | select(.comments.nodes[0].author.login == "github-actions")
           | {thread_id: .id, isResolved, path, line, body: .comments.nodes[0].body}]'
  ```

## Posting

1. Write the review to `review.json` and post it:

   ```sh
   gh api --method POST "repos/$GH_REPO/pulls/$PR_NUMBER/reviews" --input review.json
   ```

   ```json
   { "commit_id": "<HEAD_SHA>", "event": "COMMENT",
     "body": "<one to three sentence summary>",
     "comments": [ { "path": "<file>", "line": <line in the new file>, "body": "<the comment>" } ] }
   ```

   Put each issue in `comments`, on its line.
2. If GitHub rejects the review with a 422 (it couldn't place a line), post one comment with the full review instead, each issue under its header with its file and line:

   ```sh
   gh pr comment "$PR_NUMBER" --body "<your review in markdown>"
   ```

3. Always use event `COMMENT`.

New commits were pushed. You already reviewed this PR in this conversation.

Sync the clone, then review what changed since your last review:

```sh
cd "$REPO_DIR" && git diff "$BEFORE_SHA" "$HEAD_SHA"
```

Use the whole PR diff for context. If `BEFORE_SHA` isn't set, or this fails (the branch was force-pushed or rebased), review the whole PR diff instead:

```sh
cd "$REPO_DIR" && git merge-base --is-ancestor "$BEFORE_SHA" "$HEAD_SHA"
```

Fetch your earlier review threads. For each unresolved one:

- If the new code fixes it, reply with a check mark and resolve the thread:

  ```sh
  gh api graphql -f thread=<thread_id> -f body="✅ Fixed in ${HEAD_SHA:0:7}" -f query='
    mutation($thread: ID!, $body: String!) {
      addPullRequestReviewThreadReply(input: {pullRequestReviewThreadId: $thread, body: $body}) { comment { id } }
      resolveReviewThread(input: {threadId: $thread}) { thread { isResolved } } }'
  ```

- If it's still a problem, leave it alone. Don't post it again.

Only resolve your own threads, and only when the code fixes them. Post comments only for problems that are new. If there's nothing new, skip the review; don't post an empty one.