How it works

What a contributor sees, and what you set up

Every screenshot below is from the live app on a real fork pull request. The numbers shown are the defaults, and each one can be changed per repository: see the settings.

For contributors

Five steps, about three minutes

01

The check goes red

PullViva looks at who opened the pull request. A contributor you chose to quiz gets a failing check: "Answer a few questions about this PR (about 3 min)". The check is required, so the merge waits. GitHub may also ask a maintainer to approve the repo's own workflows for a first-time contributor. That is GitHub, not PullViva.

Ar9av and others added 3 commits 27 minutes ago
PullViva demo change195ade8
Document the retry policyVerified457f1f7
Document the request timeoutVerified27a9dfd
1 workflow awaiting approvalThis workflow requires approval from a maintainer. Learn more about approving workflows.
PullViva — Answer a few questions about this PR (about 3 min)Required
02

Sign in and prove a person is there

The check's Details link opens PullViva. The contributor signs in with GitHub, so the result belongs to one account, and Cloudflare Turnstile confirms a person is present. No questions are written until both pass, so automated spam costs nothing.

Signed in as metapodder

One quick check before this merges

Ar9av/clippy #5. 5 questions about your diff, with a 10 minute limit.

Success!CLOUDFLAREPrivacy · Help
Start the quiz
03

Questions about the diff

The model reads the diff and writes multiple-choice questions (five by default, from 3 to 10): what changed, why, an edge case, a risk, and how to verify it. The answer key stays on the server and the questions are not posted in the PR. There is a 10 minute limit. A miss shows which questions to re-read, never the answers.

Question set

Questions about your PR

Answer from your own understanding of the change.

1What retry behavior does the new document describe for eligible failed API calls?
Retry up to three times with exponential delays of 1, 2, and 4 seconds.
Retry up to three times with fixed delays of 1 second each.
Retry every failed API call up to three times with exponential delays.
Retry up to four times with exponential delays of 1, 2, 4, and 8 seconds.
2Why does the documented policy reuse an idempotency key across retries?
So a retried request cannot be applied twice.
So the server can skip authentication.
So delays stay constant.
So retries are logged separately.
04

Pass, and the check goes green

The pass mark is 60% by default, and you can change it. A pass clears every other open PR by that author in the repo, and they are trusted there for 30 days. A fail starts a 30 minute cooldown, and the next attempt gets a fresh set of questions. There are three attempts in total.

You passed

5 of 5 correct. The check on your PR is now green.

05

The check turns green

On GitHub the same check now reads Verified, and the commit on the PR is green. If the contributor pushes more commits later, the check is evaluated again.

Ar9av and others added 3 commits 29 minutes ago
PullViva demo change195ade8
Document the retry policyVerified457f1f7
Document the request timeoutVerified27a9dfd
1 workflow awaiting approvalThis workflow requires approval from a maintainer. Learn more about approving workflows.
PullViva — VerifiedRequired
No conflicts with base branchChanges can be cleanly merged.

For maintainers

Set up in three steps

  1. Install the app on the repositories you want to protect, from the GitHub Apps page.
  2. Require the check. In Settings, Rules, Rulesets, add a required status check named PullViva and set its source to the PullViva app. Pinning the source stops anyone else posting a check with that name. Without this step the install does nothing.
  3. Optional: host it yourself. It is one Cloudflare Worker. Bring a key for any LLM provider that offers an OpenAI-compatible API, or Anthropic's.

Let your agent do it

Set it up from your coding agent

Paste this into Claude Code, Codex, Cursor or any agent that can run shell commands. It installs nothing on its own: it asks you before each change on GitHub, and you click the one consent screen that GitHub requires.

Read https://pullviva.fyi/agent-setup.md and set up PullViva on this repository. Ask me before anything that changes GitHub.

The agent checks you are an admin, asks a few questions, adds .github/pullviva.yml, confirms the check appears on a test pull request, and only then makes it required. Read the file it follows

Who gets quizzed

AuthorResult
First-time contributor, or no prior associationQuizzed by default. gate.who can widen this.
Anyone with write, maintain or admin accessNot quizzed, even if GitHub mislabels their membership, unless gate.who is everyone or they are listed in gate.always_quiz_users
BotsNever quizzed
An author who already passedTrusted in that repo for gate.trust_days (30 by default)

Pull requests with several contributors

By default only the person who opened the pull request is checked. Set gate.co_authors to all and everyone who committed has to pass.

Who is on the pull requestauthor (default)all
First-time contributor aloneQuizzedQuizzed
Contributor, plus a maintainer who pushed a fixContributor quizzedContributor quizzed. The maintainer has write access, so is skipped
Two first-time contributorsOnly the opener quizzedBoth quizzed. The check turns green when the second one passes
Maintainer opens it, a first-time contributor's commits are on the branchNot requiredThe contributor is quizzed
Bots, exempt_users, drafts, exempt labelsSkippedSkipped

Everyone uses the same Details link and gets their own quiz. Read the details

Configure it

Decide who is quizzed, and how

There are two ways. The dashboard is a form: sign in with GitHub, pick a repository where you are an admin or maintainer, and save. Or commit .github/pullviva.yml to the default branch. When both exist, the file wins for any key it sets, so settings in git stay authoritative. Put a file in a .github repository in your account or organization for defaults across all repositories. Nothing is read from pull requests, so a fork cannot loosen its own rules.

# .github/pullviva.yml  (every key is optional)
gate:
  who: new                  # new | outside | everyone
  co_authors: author        # author | all (all = everyone who committed must pass)
  exempt_users: [octocat]   # never quizzed
  always_quiz_users: []     # always quizzed, even with write access
  exempt_labels: [pullviva-skip]
  drafts: skip              # skip | quiz
  branches: [main]          # only PRs into these branches
  paths_ignore: ["**/*.md", "docs/**"]
  min_changed_lines: 10
  trust_days: 30            # 0 = every PR needs its own pass
quiz:
  questions: 5              # 3 to 10
  pass_mark: 60             # percent
  attempts: 3
  cooldown_minutes: 30
  time_limit_minutes: 10
  difficulty: standard      # easy | standard | hard
  focus: [error handling, security]
  language: English
  extra_instructions: Prefer questions about the public API.
behavior:
  on_llm_error: fail_closed # fail_closed | fail_open

A mistake never breaks the check. A bad value falls back to its default, and the problem is listed under Config warnings in the check's summary.

SettingDefaultWhat it does
gate.enabledtruefalse turns PullViva off for the repository: the check passes as Not required and nobody is quizzed.
gate.co_authorsauthorauthor checks only the person who opened the PR. all also requires every other commit author (not bots, not exempt, no write access) to pass; the check turns green when the last one does.
gate.whonewnew quizzes first-time contributors. outside quizzes anyone without write access. everyone quizzes every human author, maintainers included.
gate.exempt_usersnoneGitHub logins that are never quizzed.
gate.always_quiz_usersnoneLogins that are always quizzed, even with write access. Their trust window is ignored.
gate.exempt_labelsnoneA pull request with any of these labels skips the quiz.
gate.draftsskipskip waits until the pull request is ready for review. quiz checks drafts too.
gate.branchesallOnly gate pull requests into these base branches.
gate.paths_ignorenoneGlob patterns. If every changed file matches, the pull request passes without a quiz. Looks at the first 100 files.
gate.min_changed_lines0Pull requests that change fewer lines than this pass without a quiz.
gate.trust_days30After a pass, the author skips the quiz in this repository for this many days. 0 turns trust off.
quiz.questions5How many questions, from 3 to 10.
quiz.pass_mark60Percent correct needed to pass.
quiz.attempts3Attempts per pull request before only a maintainer can pass it.
quiz.cooldown_minutes30Wait after a failed attempt. Each retry gets a fresh set of questions.
quiz.time_limit_minutes10Time allowed for one attempt.
quiz.difficultystandardeasy asks about the main idea. hard asks about subtle consequences and edge cases.
quiz.focuswhat, why, edge case, risk, verificationTopics the questions should cover, for example security or error handling.
quiz.languageEnglishLanguage of the questions and answers.
quiz.extra_instructionsnoneUp to 600 characters of guidance for whoever writes the questions.
behavior.on_llm_errorfail_closedIf questions cannot be written: fail_closed keeps the check red, and a maintainer can override. fail_open lets it pass.

What is stored

The diff goes to the model provider to write the questions and is not stored. PullViva keeps the questions and scores, attempt times, the PR number and the author's numeric GitHub ID. A quiz is a filter, not proof: someone with a chatbot in another tab can still pass.

Try it on one repository

Install on GitHub