How it works
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
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.
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
Ar9av/clippy #5. 5 questions about your diff, with a 10 minute limit.
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
Answer from your own understanding of the change.
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.
5 of 5 correct. The check on your PR is now 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.
For maintainers
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.Let your agent do it
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
| Author | Result |
|---|---|
| First-time contributor, or no prior association | Quizzed by default. gate.who can widen this. |
| Anyone with write, maintain or admin access | Not quizzed, even if GitHub mislabels their membership, unless gate.who is everyone or they are listed in gate.always_quiz_users |
| Bots | Never quizzed |
| An author who already passed | Trusted in that repo for gate.trust_days (30 by default) |
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 request | author (default) | all |
|---|---|---|
| First-time contributor alone | Quizzed | Quizzed |
| Contributor, plus a maintainer who pushed a fix | Contributor quizzed | Contributor quizzed. The maintainer has write access, so is skipped |
| Two first-time contributors | Only the opener quizzed | Both quizzed. The check turns green when the second one passes |
| Maintainer opens it, a first-time contributor's commits are on the branch | Not required | The contributor is quizzed |
Bots, exempt_users, drafts, exempt labels | Skipped | Skipped |
Everyone uses the same Details link and gets their own quiz. Read the details
Configure it
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.
| Setting | Default | What it does |
|---|---|---|
gate.enabled | true | false turns PullViva off for the repository: the check passes as Not required and nobody is quizzed. |
gate.co_authors | author | author 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.who | new | new quizzes first-time contributors. outside quizzes anyone without write access. everyone quizzes every human author, maintainers included. |
gate.exempt_users | none | GitHub logins that are never quizzed. |
gate.always_quiz_users | none | Logins that are always quizzed, even with write access. Their trust window is ignored. |
gate.exempt_labels | none | A pull request with any of these labels skips the quiz. |
gate.drafts | skip | skip waits until the pull request is ready for review. quiz checks drafts too. |
gate.branches | all | Only gate pull requests into these base branches. |
gate.paths_ignore | none | Glob patterns. If every changed file matches, the pull request passes without a quiz. Looks at the first 100 files. |
gate.min_changed_lines | 0 | Pull requests that change fewer lines than this pass without a quiz. |
gate.trust_days | 30 | After a pass, the author skips the quiz in this repository for this many days. 0 turns trust off. |
quiz.questions | 5 | How many questions, from 3 to 10. |
quiz.pass_mark | 60 | Percent correct needed to pass. |
quiz.attempts | 3 | Attempts per pull request before only a maintainer can pass it. |
quiz.cooldown_minutes | 30 | Wait after a failed attempt. Each retry gets a fresh set of questions. |
quiz.time_limit_minutes | 10 | Time allowed for one attempt. |
quiz.difficulty | standard | easy asks about the main idea. hard asks about subtle consequences and edge cases. |
quiz.focus | what, why, edge case, risk, verification | Topics the questions should cover, for example security or error handling. |
quiz.language | English | Language of the questions and answers. |
quiz.extra_instructions | none | Up to 600 characters of guidance for whoever writes the questions. |
behavior.on_llm_error | fail_closed | If questions cannot be written: fail_closed keeps the check red, and a maintainer can override. fail_open lets it pass. |
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.