Closes #23413: Implement Vouch to mitigate spam PRs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.github/DISCUSSION_TEMPLATE/vouch-request.yml

@@ -0,0 +1,41 @@
+body:
+  - type: markdown
+    attributes:
+      value: |
+        > [!IMPORTANT]
+        > This form is for **first-time contributors**, who must be vouched for before submitting pull requests. Please read through our [contributing guide](https://github.com/netbox-community/netbox/blob/main/CONTRIBUTING.md) before proceeding.
+        >
+        > Please keep your introduction **concise** and write it **in your own words**. Do not use AI to write it for you. Once your request has been approved, a maintainer will reply with `!vouch` and you will be able to submit pull requests.
+  - type: textarea
+    attributes:
+      label: About you
+      description: >
+        Tell us a bit about yourself. What is your background, and how do you use NetBox?
+      placeholder: >
+        I'm a network engineer at a regional ISP, and we've been using NetBox to manage our...
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Why do you want to contribute?
+      description: >
+        What motivates you to contribute to NetBox? If you have a specific change in mind, please link to the
+        relevant issue (e.g. #1234).
+      placeholder: >
+        I'd like to work on #1234, which affects our deployment because...
+    validations:
+      required: true
+  - type: checkboxes
+    attributes:
+      label: "I acknowledge that:"
+      options:
+        - label: >-
+            I wrote this introduction myself, in my own words, without the use of AI.
+          required: true
+        - label: >-
+            I have read the [contributing guide](https://github.com/netbox-community/netbox/blob/main/CONTRIBUTING.md)
+            and understand the contribution process.
+          required: true
+        - label: >-
+            I must wait to be assigned as the owner of an issue before submitting a PR for it.
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,11 +2,13 @@
     Thank you for your interest in contributing to NetBox! Before submitting a
     PR, please verify the following:
 
-      1. An issue has been opened to capture these changes
-      2. The issue has been accepted and assigned to you for work
+      1. You have been vouched for as a contributor (see CONTRIBUTING.md)
+      2. An issue has been opened to capture these changes
+      3. The issue has been accepted and assigned to you for work
 
-    Pull requests which do not reference an assigned issue will be closed
-    automatically. Please specify your assigned issue number on the line below.
+    Pull requests from contributors who have not been vouched for, or which
+    do not reference an assigned issue, will be closed automatically. Please
+    specify your assigned issue number on the line below.
 -->
 ### Closes: #1234
 

.github/VOUCHED.td

@@ -0,0 +1,142 @@
+# The list of vouched (or actively denounced) users for this repository.
+#
+# Only vouched users may submit pull requests to this project. A denounced
+# user is explicitly blocked from contributing.
+#
+# Syntax:
+#  - One handle per line (without @). Sorted alphabetically.
+#  - Optionally specify platform: `platform:username` (e.g. `github:jeremystretch`).
+#  - To denounce a user, prefix with minus: `-username` or `-platform:username`.
+#  - Optionally, add comments after a space following the handle.
+#
+# Maintainers can vouch for new contributors by commenting "!vouch" on a
+# discussion by the author. Maintainers can also comment "!unvouch" to remove
+# a user, or "!denounce" (optionally "!denounce [username]") to denounce one.
+#
+# See https://github.com/mitchellh/vouch for details.
+
+991jo
+9er-tom
+Abhirupmandal
+abrahamvegh
+abubnalitic-nbl
+adamboutcher
+adionit7
+alehaa
+alexhoulton
+AliMickey
+Amir-Bakar
+antoinekh
+aq5747
+arthanson
+ascjreddy
+atownson
+attoba
+backeby
+bctiemann
+bevand10
+blackphantom39
+bluikko
+carlosalbertorg
+chbndrhnns
+ciroiriarte
+clovehitch
+cmdrrobin
+cocofabio
+corubba
+DanSheps
+dfex
+dianbofa
+dkrasthi
+dmismirn
+dreng
+dxks
+DylanLucci
+Etibru
+fabi125
+fanshan
+g-builder-0
+GeertJohan
+gizmonicus
+grische
+Guibi1
+Haeki
+harryajc
+hblandford
+ianb-mp
+ifoughal
+IPB-DevOps
+ITJamie
+jamestiotio
+Jathn
+jchambers2012
+JCWasmx86
+jeremypng
+jeremystretch
+jetomit
+jkburges
+jmcguir
+jmouette
+jniec-js
+jnovinger
+jseifeddine
+jsenecal
+Juice-de-Orange
+kartik-lamkhade
+kprince28
+kyerlasswell
+larsen0815
+lasseh
+lexapi
+llamafilm
+m-hau
+magicalyak
+Maksym-Ototiuk
+MarcoSpiz
+markkuleinio
+marsteel
+matejv
+Mathias-gt
+mathieumd
+matthew-242
+mburggraf
+mderekasir
+mi3law
+miaow2
+mo-hossam-stack
+mollona
+mr1716
+mraerino
+mrmrcoleman
+mskalecki
+nfvelten
+Olexandr88
+Omripresent
+peteeckel
+pheus
+PieterL75
+piyush-003
+pl0xym0r
+pobradovic08
+renatoalmeidaoliveira
+rfdrake
+rinna11
+robduffy2010
+RobertH1993
+rodvand
+sergiolpzgmz
+stalker-nn
+studioussagar
+stuntguy3000
+swoga
+thordreier
+Tishka17
+tobiasge
+UnknownTy
+vo42
+Wyrtrorm
+xee8ai
+YiPrograms
+ypid
+ypid-work
+ZPrimed

.github/vouch-pr-unvouched-message

@@ -0,0 +1,7 @@
+Hi @{author}, thanks for your interest in contributing to NetBox!
+
+Pull requests to this repository can be submitted only by contributors who have been vouched for by a maintainer, and you are not yet on the list of vouched contributors. To request a vouch, please introduce yourself by [starting a discussion](https://github.com/{owner}/{repo}/discussions/new?category=vouch-request) in the **Vouch Request** category. Once a maintainer has vouched for you, you're welcome to submit a new pull request.
+
+Please see our [contributing guide](https://github.com/{owner}/{repo}/blob/{default_branch}/CONTRIBUTING.md) for more details.
+
+This pull request will be closed automatically.

.github/workflows/vouch-check-pr.yml

@@ -0,0 +1,30 @@
+# vouch (https://github.com/mitchellh/vouch)
+name: Vouch - Check PR
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check:
+    if: github.repository == 'netbox-community/netbox'
+    runs-on: ubuntu-latest
+    steps:
+      # Check out the base branch (never the PR head) to read the response template
+      - name: Check out repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Check PR author
+        uses: mitchellh/vouch/action/check-pr@d66fa29a64600490892131ad87597c30c91fcac4 # v1.5.0
+        with:
+          pr-number: ${{ github.event.pull_request.number }}
+          auto-close: true
+          template-file: .github/vouch-pr-unvouched-message
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/vouch-manage-by-discussion.yml

@@ -0,0 +1,46 @@
+# vouch (https://github.com/mitchellh/vouch)
+name: Vouch - Manage by discussion
+
+on:
+  discussion_comment:
+    types: [created]
+
+permissions:
+  contents: read
+
+# Serialize updates to the VOUCHED file
+concurrency:
+  group: vouch-manage
+  cancel-in-progress: false
+
+jobs:
+  manage:
+    # Skip comments which can't contain a vouch command
+    if: github.repository == 'netbox-community/netbox' && startsWith(github.event.comment.body, '!')
+    runs-on: ubuntu-latest
+    steps:
+      # An app token is required to merge the VOUCHED update into the protected default branch
+      - name: Create app token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        id: app-token
+        with:
+          app-id: 1076524
+          private-key: ${{ secrets.HOUSEKEEPING_SECRET_KEY }}
+
+      - name: Check out repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Update VOUCHED file
+        uses: mitchellh/vouch/action/manage-by-discussion@d66fa29a64600490892131ad87597c30c91fcac4 # v1.5.0
+        with:
+          discussion-number: ${{ github.event.discussion.number }}
+          comment-node-id: ${{ github.event.comment.node_id }}
+          vouch-keyword: "!vouch"
+          denounce-keyword: "!denounce"
+          unvouch-keyword: "!unvouch"
+          pull-request: "true"
+          merge-immediately: "true"
+        env:
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}

AGENTS.md

@@ -280,16 +280,21 @@ GitHub Actions workflows in `.github/workflows/`:
 1. **Issue reference required** — The PR body must include a `Closes: #<number>` line identifying the associated GitHub issue. PRs without this line must not be submitted.
 2. **Issue must be open** — Before opening a PR, verify via `gh issue view <number>` that the referenced issue is currently open. Do not submit a PR against a closed issue.
 3. **Issue must be assigned to you** — Verify that the referenced issue is assigned to the submitting user. Do not open a PR for an issue that is unassigned or assigned to someone else.
-4. **No exceptions without maintainer status** — These three requirements are waived only for project maintainers (members of the `netboxlabs` GitHub organization). All other contributors must satisfy all three checks before a PR is opened.
+4. **Author must be vouched** — Pull requests are accepted only from contributors listed in `.github/VOUCHED.td` on the default branch; PRs from anyone else are closed automatically. If the submitting user is not listed, do not open the PR; instead, direct them to request a vouch by [starting a discussion](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) in the **Vouch Request** category, written in their own words.
+5. **No exceptions without maintainer status** — These requirements are waived only for project maintainers (members of the `netboxlabs` GitHub organization). All other contributors must satisfy all four checks before a PR is opened.
 
 **Pre-submission checklist for AI agents:**
 
 ```bash
 # Confirm the issue is open and assigned before opening a PR
 gh issue view <number> --json state,assignees
+
+# Confirm the submitting user is vouched (no output means not vouched)
+gh api repos/netbox-community/netbox/contents/.github/VOUCHED.td -H "Accept: application/vnd.github.raw" \
+  | grep -iE "^(github:)?$(gh api user -q .login)( |$)"
 ```
 
-Reject the PR submission and report the problem if the issue is closed, unassigned, or assigned to a different user.
+Reject the PR submission and report the problem if the issue is closed, unassigned, or assigned to a different user, or if the submitting user has not been vouched for.
 
 Do not include an entry in the release notes for the PR unless explicitly instructed to do so. (Release notes are typically generated in aggregate as part of the release process to avoid merge conflicts.)
 

CONTRIBUTING.md

@@ -85,11 +85,17 @@ intake policy](https://github.com/netbox-community/netbox/wiki/Issue-Intake-Poli
   * A maintainer triages the issue and may mark it as needing an owner
   * The issue's author can volunteer to own it, or someone else can
   * A maintainer assigns the issue to whomever volunteers
-  * The issue owner submits a pull request that will resolve the issue
+  * If they haven't contributed before, the volunteer [requests a vouch](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) (see below)
+  * The volunteer submits a pull request that will resolve the issue
   * A maintainer reviews and merges the pull request, closing the issue
 
 * It's very important that you not submit a pull request until a relevant issue has been opened **and** assigned to you. Otherwise, you risk wasting time on work that may ultimately not be needed.
 
+* Pull requests are accepted only from contributors who have been vouched for by a maintainer. (We use [Vouch](https://github.com/mitchellh/vouch) to manage this.) If you're contributing for the first time, please introduce yourself by [starting a discussion](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) in the **Vouch Request** category, telling us a bit about your background and why you'd like to contribute. Once a maintainer has approved your request, you'll be added to the list of [vouched contributors](https://github.com/netbox-community/netbox/blob/main/.github/VOUCHED.td) and can begin submitting pull requests. Pull requests from contributors who have not been vouched for are closed automatically.
+
+> [!IMPORTANT]
+> Please write your vouch request yourself, in your own words. We want to get to know the person behind the contributions; requests that appear to be generated by AI will not be approved.
+
 * Community members are limited to a maximum of **three open PRs** at any time. This is to avoid the accumulation of too much parallel work and maintain focus on PRs already under review. If you already have three NetBox PRs open, please wait for at least one of them to be merged (or closed) before opening another.
 
 * New pull requests should generally be based off of the `main` branch. This branch, in keeping with the [trunk-based development](https://trunkbaseddevelopment.com/) approach, is used for ongoing development and bug fixes and always represents the newest stable code, from which releases are periodically branched. (If you're developing for an upcoming minor release, use `feature` instead.)

docs/development/getting-started.md

@@ -200,6 +200,9 @@ UPDATE_QUERY_COUNTS=1 python manage.py test --keepdb
 
 ## Submitting Pull Requests
 
+!!! note "First-time contributors"
+    Pull requests are accepted only from contributors who have been vouched for by a maintainer. If you haven't contributed to NetBox before, introduce yourself by [starting a discussion](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) in the **Vouch Request** category before submitting your first pull request. Pull requests from contributors who have not been vouched for are closed automatically. See the [contributing guide](https://github.com/netbox-community/netbox/blob/main/CONTRIBUTING.md) for details.
+
 Once you're happy with your work and have verified that all tests pass, commit your changes and push it upstream to your fork. Always provide descriptive (but not excessively verbose) commit messages. Be sure to prefix your commit message with the word "Fixes" or "Closes" and the relevant issue number (with a hash mark). This tells GitHub to automatically close the referenced issue once the commit has been merged.
 
 ```no-highlight