# Set up PullViva with your coding agent

Paste this into Claude Code, Codex, Cursor or any agent that can run shell commands:

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

The rest of this file is written for the agent.

---

## What PullViva is
A GitHub App that adds a required check named `PullViva`. When a contributor who is in scope opens a pull request, the check is red until they sign in with GitHub and pass a short quiz about their own diff. Docs: https://pullviva.fyi/learn. Source: https://github.com/Ar9av/pullviva.

## Rules for you
- Do the steps in order and stop to ask the user where marked **ASK**.
- Never print, log or commit secrets. You will not need any.
- Do not give the app more permissions than it asks for. It must never have Administration.
- Do not make the check required until step 3 is confirmed. A required check from an app that is not installed blocks every merge.
- Use `gh` (GitHub CLI). If `gh auth status` fails, ask the user to run `gh auth login`.

## 0. Check access
```bash
gh repo view --json nameWithOwner,defaultBranchRef,viewerPermission
```
`viewerPermission` must be `ADMIN` (needed for rulesets). If it is not, tell the user and stop. Remember `OWNER/REPO` and the default branch.

## 1. ASK: choices
Ask the user these, offering the default in brackets. Skip any they have no opinion on.
1. Who is quizzed? `new` first-time contributors [default], `outside` anyone without write access, `everyone`.
2. Pull requests with several contributors: `author` only the opener [default], or `all` everyone who committed (see https://github.com/Ar9av/pullviva/blob/main/docs/multiple-contributors.md).
3. Skip docs-only changes? If yes, `paths_ignore: ["**/*.md", "docs/**"]`.
4. Quiz size: number of questions (3 to 10), pass mark and attempts [defaults: 5 questions, 60%, 3 attempts].
5. Anyone who should never be quizzed (`exempt_users`).

## 2. Install the app (the user does this part)
Installing an app needs the user's consent in a browser, so you cannot do it. Give the user this link and ask them to choose this repository only:

https://github.com/apps/pullviva/installations/new

Wait for them to say it is done. Do not continue until they have.

## 3. Add the config on the default branch
Settings are read from the default branch only, never from a pull request. Create `.github/pullviva.yml` with only the keys the user changed (every key is optional):

```yaml
gate:
  who: new
  co_authors: author
  paths_ignore: ["**/*.md", "docs/**"]
quiz:
  questions: 5
  pass_mark: 60
```

All options: https://github.com/Ar9av/pullviva/blob/main/pullviva.example.yml. Commit it on a branch and open a pull request, or push to the default branch if the user says that is fine. If the user prefers a web form, the same settings live at https://pullviva.fyi/dashboard and need no file.

## 4. Verify the app is working
Open a small test pull request (a change to a README line is enough), or use an existing open one:
```bash
gh pr checks <number>
```
A check named `PullViva` must appear. If the author has write access it will say `Not required`, which is correct and proves the app is running. If nothing appears after a minute, the app is not installed on this repository: go back to step 2.

## 5. ASK, then make the check required
Tell the user this will block merges until `PullViva` passes, and ask for a yes. Then create a ruleset. `5870974` is PullViva's public GitHub App id, which pins the check to the real app so nothing else can post a check with the same name.

```bash
gh api -X POST repos/OWNER/REPO/rulesets --input - <<'JSON'
{
  "name": "require-pullviva",
  "target": "branch",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [
    { "type": "required_status_checks",
      "parameters": {
        "strict_required_status_checks_policy": false,
        "required_status_checks": [ { "context": "PullViva", "integration_id": 5870974 } ]
      } }
  ]
}
JSON
```
Replace `OWNER/REPO`. If the repository already has a ruleset or branch protection that requires checks, add `PullViva` there instead of creating a second one. Repositories that use a merge queue need nothing extra: PullViva passes `merge_group` runs automatically.

## 6. Report back
Tell the user, in a few lines: what you changed (the config file, the ruleset), what a contributor will see (a red `PullViva` check with a Details link to the quiz), that maintainers can use **Mark as passed** on the check, and that they can change any setting later at https://pullviva.fyi/dashboard.

## Troubleshooting
| Symptom | Cause |
|---|---|
| No `PullViva` check on new PRs | App not installed on this repo, or installed with no repository selected |
| Merges blocked and no check ever appears | The ruleset exists but the app is not installed. Install it, or delete the ruleset |
| Check says `Not required` for a first-time contributor | Draft PR, exempt label or user, a `branches` or `paths_ignore` rule, or the author has write access |
| Config warning in the check summary | A value in `pullviva.yml` was invalid and its default is used instead. The summary names the key |
