Skip to Content
Platform
How-toReview every pull request

Review every pull request

Every pull request gets a review from your agent, posted on GitHub like any other reviewer’s.

A GitHub Action calls introspection tasks create with the pull request’s head commit; the agent reads the checkout and posts a review with gh pr review. GitHub events don’t start tasks by themselves: the Action is the trigger.

You need: a deployed runtime (Deploy), the repository registered in the project (Let the agent work on your code), and a production API key (Credentials).

1. Grant the runtime the repository

Reads are implicit; add pull-requests: write and leave out contents: write.

.introspection/pr-reviewer.yaml
runtime:
  github:
    repositories:
      - acme/api-service
    permissions:
      pull-requests: write

Run introspection check and merge; the grant ships with the next version.

2. Tell the agent how to review

agents/agent.yaml
tools: [read, bash]
system_instructions:
  mode: append
  content: |
    You review one pull request. Work in workspace/repos/<name>. Read the diff
    against the base branch, then post exactly one review with
    `gh pr review <number> --comment --body-file review.md`. Never approve,
    push, or merge.

3. Store the API key in GitHub

gh secret set INTROSPECTION_TOKEN --repo acme/api-service

Paste the key when prompted.

4. Add the workflow

.github/workflows/agent-review.yml
name: Agent review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review]
 
jobs:
  review:
    if: ${{ !github.event.pull_request.draft }}
    runs-on: ubuntu-latest
    steps:
      - run: npm install -g @introspection-ai/cli
      - env:
          INTROSPECTION_TOKEN: ${{ secrets.INTROSPECTION_TOKEN }}
          INTROSPECTION_PROJECT: <project-slug>
          REPO: ${{ github.repository }}
          PR: ${{ github.event.pull_request.number }}
          SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          introspection tasks create --runtime pr-reviewer --environment production \
            --repository "$REPO@$SHA" --tag pr:"$PR" \
            --prompt "Review pull request #$PR in $REPO at commit $SHA."

--repository OWNER/NAME@REF takes a branch, tag, or full SHA. The review arrives a few minutes after the job ends.

Verify

gh run list --workflow agent-review.yml --limit 1
introspection tasks list --limit 5 -o table
gh pr view <number> --comments

Expect a green Action run, a task for the pull request, and one review from the Introspection app.

Or ask your agent: “Set up an agent review on every pull request in acme/api-service.”

Limits

ProblemDo this
No checkout in the taskRegister the repository, list it in runtime.github.repositories, and ship the grant. Unlisted repositories are dropped silently.
gh pr review permission errorAdd pull-requests: write, ship it, and check the GitHub App installation allows it.
Pull requests from forksGitHub hides secrets from fork workflows: skip them with if: github.event.pull_request.head.repo.full_name == github.repository.
Several reviews on one pull requestEach push starts a task: tell the agent to update its earlier review, or drop synchronize.
Reading workflow run logsPass the log in the prompt, or --file @./build.log.
Fixing review commentsA second runtime with contents: write, started on the head branch on pull_request_review.
Continuing on a later issue commentStore the task ID per issue and send each comment with tasks prompt (grant issues: write).
Last updated on