CLI tool
mitchellh/vouch avatar
mitchellh/vouch

Vouch: a flat-file trust list for open source projects

A community trust management system based on explicit vouches to participate.

5,177 stars91 forksNushellMIT

At a glance

What is it?
Vouch gates issues and pull requests behind an explicit vouch list kept in one text file. It is a Nushell module with GitHub Actions wrappers, and the README calls it experimental.
Who is it for?
Adopt Vouch if your project already has a small group of maintainers willing to curate a vouch file and you want issue and PR gating handled by a GitHub Action rather than a bot with a database. Do not adopt it if you need a hosted service, a web dashboard, or a policy that a non-maintainer can administer, because the project leaves the who and how entirely to you and ships no policy engine.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 35 days ago.
What is it written in?
Mainly Nushell, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • mitchellh/vouch5,177 ★ · +62
Star history
Repository2026-09-232026-11-15
mitchellh/vouch5.1k5.2k

62 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The problem Vouch addresses: contribution gates after AI-generated noise

The README states the motivation directly: the effort required to understand a codebase and submit a change used to filter out low quality contributions, and that filter no longer holds once plausible-looking patches are cheap to produce. Vouch replaces the implicit filter with an explicit one. A person must be vouched for before interacting with the parts of a project you choose to gate, and a person can be denounced to block them outright. The intended audience is maintainers of projects large enough that strangers arrive with patches but small enough that a maintainer still recognises the names of trusted contributors. The README notes the system is based on one already in use by the Pi project, that it is in use by Ghostty, and carries a warning that it is experimental. Nothing in the documentation defines who may vouch. That decision, and the consequences of being vouched or denounced, are left to the integrating project.

How the vouch list works: one flat file, three exit codes

The state lives in a single flat file in a minimal format the README says can be parsed with standard POSIX tools and any language without external libraries. The repository ships VOUCHED.example.td as the shape to copy. The CLI is a Nushell module, so the runtime dependency is Nushell and nothing else. The core read operation is a status check with three outcomes mapped to process exit codes: 0 for vouched, 1 for denounced, 2 for unknown. That mapping is the whole integration surface for a shell script or a CI step, and it is the cleanest part of the design. The GitHub side is a set of Actions rather than a service: check-issue and check-pr run on issue and pull request events, check-user answers the same question for any workflow, manage-by-issue and manage-by-discussion let collaborators change the list by commenting, sync-codeowners pulls CODEOWNERS entries into the list, and setup-vouch puts the CLI on PATH, installing Nushell if it is missing. The README states that bots and collaborators with write access are automatically allowed by the check actions, which is the escape hatch that keeps maintainers from having to vouch for themselves.

Installing the vouch CLI and running a first check

The README points to the GitHub Actions directory for integration and describes the CLI as a Nushell module, so the practical path is the setup-vouch action, or loading the module from the repository yourself. The repository root contains a flake.nix and a shell.nix, which is where a Nix user would look. To load the module and read the built-in help, the README shows this:

nu
use vouch *
help add
help check
help denounce
help gh-check-issue
help gh-check-pr
help gh-manage-by-issue

Once the module is loaded, checking a user returns a status through the exit code rather than parsing output. A vouched user exits 0, a denounced user exits 1, and an unknown user exits 2:

bash
vouch check <username>

The add and denounce commands preview the new file contents by default and only write when passed --write, which is the right default for a file that gates contributions:

bash
vouch add someuser
vouch add someuser --write
vouch denounce badactor --reason "Submitted AI slop"
vouch denounce badactor --write

For the GitHub path, the README gives this sequence. The README marks both commands as dry runs, and labels a further --auto-close variant as the one that actually closes unvouched issues:

bash
vouch gh-check-issue 123 --repo owner/repo
vouch gh-check-issue 123 --repo owner/repo --auto-close

The GitHub commands read GITHUB_TOKEN from the environment, and the README states that if it is unset and gh is available, the token from gh auth token is used instead.

The --dry flag inverts what you would expect

Read the CLI examples carefully. In the local commands, the default is a preview and --write commits the change. In the GitHub commands, the README's own comment marks --auto-close on its own as still a dry run, and a further flag is needed before issues are actually closed. A maintainer skimming the block may read --auto-close as the enabling flag and wire a workflow that never closes anything. This is a documentation and interface problem rather than a functional one, and it is the first thing I would verify against the action READMEs before trusting a workflow. It is also the kind of detail that makes the experimental label in the README feel earned rather than cautious.

Where Vouch is the wrong tool

Vouch has no policy engine. The README is explicit that who is vouched, how, and what consequences follow are entirely up to the integrating project. If you need per-directory rules, time-limited vouches, appeals, or an audit trail beyond git history, you are building that yourself on top of a flat file. The file is also a single point of contention: every vouch and denounce is a write to one file, and the manage-by-issue and manage-by-discussion actions commit those writes, so concurrent changes from several collaborators land on the same path. A project with hundreds of active contributors and a rotating moderation team will find the flat file and the comment-driven workflow thin. And the gating itself is coarse. The check actions run on issue and pull request events; they do not inspect the contents of a patch. A vouched account that later submits a bad change passes the gate, which is the intended trade-off but worth stating plainly, because the README's framing about low-quality contributions can read as if the check evaluates quality. It does not. It evaluates whether a name is in a file.

Alternatives and the actual difference in approach

The obvious comparison is the CODEOWNERS file that GitHub already supports. CODEOWNERS maps paths to reviewers and drives review requests; it does not decide whether an author may open the pull request at all. Vouch answers a different question, and it can read CODEOWNERS as an input through the sync-codeowners action, which vouches missing owners. That action is the clearest statement of the relationship: CODEOWNERS says who reviews, Vouch says who is allowed in. A second comparison is a general-purpose moderation or allowlist bot backed by a database. That approach scales to many projects and gives you queryable state, at the cost of a service to run and a schema to migrate. Vouch's counter-argument is the flat file: a diff in the repository is the entire record, reviewable in the same pull request flow as the code, and readable by any tool. If your list changes weekly and you want it visible in git, the flat file wins. If your list changes hourly across several repositories, it does not. This is my reading of the design, not a claim from the project.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-10-11. The most recent release listed is v1.5.0 on 2026-07-12, after v1.4.2 and v1.4.1 in February 2026, so the project has shipped a minor release within the last few months. The README still labels the system experimental and says it will continue to change based on experience and feedback, which means upgrades should be treated as potentially involving the file format or the action inputs rather than as drop-in patch bumps. The repository carries a flake.lock, so Nix users get a pinned dependency set. Plan to read the release notes before bumping the action references in your workflows. The licence is MIT, which permits commercial and private use and modification with the copyright notice retained; the LICENSE file is the authority, and nothing here is legal advice. One practical licence-adjacent point: the vouch list itself lives in your repository under your own terms, not the project's.

Editorial conclusion

Adopt Vouch if your project already has a small group of maintainers willing to curate a vouch file and you want issue and PR gating handled by a GitHub Action rather than a bot with a database. Do not adopt it if you need a hosted service, a web dashboard, or a policy that a non-maintainer can administer, because the project leaves the who and how entirely to you and ships no policy engine. Before wiring it into a live repository, read action/manage-by-issue/README.md and action/check-pr/README.md to confirm the auto-close and write-back behaviour matches what you expect, and check VOUCHED.example.td to see the file format your fork will commit.

Frequently asked questions

What is Vouch by mitchellh?

It is a community trust management system in which people must be vouched for before interacting with the parts of a project you choose to gate, and can be denounced to block them. The README describes it as generic, with GitHub integration provided through actions and a CLI.

How do you install the Vouch CLI?

The README describes the CLI as a Nushell module with no other external dependencies, and provides a setup-vouch action that installs the CLI on PATH and installs Nushell automatically if it is not already available.

What are the exit codes for vouch check?

The README states that vouch check returns 0 for a vouched user, 1 for a denounced user, and 2 for an unknown user.

Does Vouch work outside GitHub?

The README says the implementation is generic and can be used by any project on any code forge, but GitHub integration is the one provided out of the box through GitHub Actions and the CLI.

Who decides who gets vouched in Vouch?

The integrating project does. The README states that who and how someone is vouched or denounced, and what consequences follow, are left entirely up to the project using the system.

Official sources

  1. Issues
  2. License: MIT
  3. mitchellh/vouch on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/mitchellh-vouch.svg)](https://hysenlabs.com/projects/mitchellh-vouch)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/mitchellh-vouch.svg)](https://hysenlabs.com/projects/mitchellh-vouch)

Was this useful?