Repositories

A connected repository is what makes whitebox pentesting and automated PR review possible. Connecting one is a GitHub App installation, so it needs a browser once; everything after that is scriptable.

The repository object

Policy fields versus effective fields

Each policy is three-valued. default defers to the organization default; on and off override it for this repository alone. The effective_* booleans are that resolution already done for you.

To know what will actually happen on the next PR, read effective_*. To know whether this repository overrides the organization, read the policy field. Reading a policy field to predict behavior is the mistake to avoid — default tells you nothing on its own.

Connect a repository

The GitHub App has to be installed by a human. Three calls, one of them in a browser:

{ "install_url": "https://github.com/apps/vulnix/installations/new?state=…" }

{ "installation_id": "48210991", "state": "…" }

{ "installation_id": "48210991" }

List installations

GET /repositories/installations · scope repositories:read · role admin

{
  "installations": [
    {
      "installation_id": "48210991",
      "account_login": "acme-inc",
      "connected_at": "2026-09-16T17:11:02.884120+00:00"
    }
  ]
}

See what is available to add

GET /repositories/available · scope repositories:read · role admin

{ "has_installation": true, "repositories": [] }

Everything the installation can see but that you have not added yet. has_installation: false means no GitHub App is installed — start at connect rather than treating the empty list as "no repositories".

Add repositories

POST /repositories · scope repositories:write · role admin · returns 201

Returns { "repositories": [...] } with the full objects for everything now connected. An installation that is no longer valid returns 422 github_installation_invalid.

List and read

GET /repositories · scope repositories:read · role admin

{ "repositories": [] }

GET /repositories/{repository_id} returns one repository object.

Update policy

PATCH /repositories/{repository_id} · scope repositories:write · role admin

Sparse — omitted fields are unchanged.

curl -X PATCH https://api.vulnix.dev/repositories/$REPO_ID \
  -H "Authorization: Bearer $VULNIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"block_on_findings_policy": "on", "approve_clean_prs_policy": "default"}'

Returns the updated repository object with effective_* recomputed. Any value outside the three allowed returns 422 invalid_request.

Revoke a repository

POST /repositories/{repository_id}/revoke · scope repositories:write · role admin

Stops all review activity and drops stored access. Returns the repository object with status of revoked. Revoking one already revoked returns 409 repository_already_revoked.

Findings and PR reviews produced while it was connected are kept — revoking ends future access, it does not erase history.

Disconnect an installation

POST /repositories/installations/{installation_id}/disconnect · scope repositories:write · role admin

{ "ok": true }

Removes the whole installation and with it every repository under it. Use revoke to drop a single repository instead.