repoauditorweb

Project:

Package:

Development:

Overview
Installation
Development
Additional Information
License

Overview

RepoAuditorWeb audits GitHub repositories for best practices. Each requirement explains why it matters, and each failure includes step-by-step instructions for resolving it.

Requirements are grouped into modules:

Module	Description	Requirements	Included by Default
`GitHub`	Repository settings, rulesets, and branch protection.	43	No
`CommunityStandards`	Files in GitHub's community profile checklist, such as `README`, `CODE_OF_CONDUCT`, `CONTRIBUTING`, `LICENSE`, `SECURITY`, issue templates, and pull request templates.	7	No
`ScientificSoftware`	Files expected of scientific software, such as `CITATION.cff`.	1	No
`JOSS`	Items in the JOSS review checklist that can be evaluated automatically, such as an OSI-approved license, public development history, contributors, documentation, tests, and the `paper.md` sections, metadata, length, and references.	16	No

Every requirement has a default that can be customized or skipped, so the audit can be tailored to the conventions of a team or organization. Additional modules can be defined in separate packages; see Custom Modules.

How to use `RepoAuditorWeb`

Run repoauditorweb to open the web experience, where modules and requirements are configured before the audit is executed:

uvx repoauditorweb --url https://github.com/<owner>/<repo> --GitHub-include --CommunityStandards-include

uvx is part of uv, a Python package and project manager; it downloads and runs RepoAuditorWeb in a temporary environment, so it is not necessary to install RepoAuditorWeb first. If uvx is not available, install uv or see Installation for alternatives.

Customizing the audit in the web experience

Click Execute to run the audit. The results summarize the outcome of each requirement and, for each failure, describe how to resolve it and the rationale behind the requirement's default:

Results for a repository that does not satisfy the requirements

Auditing Multiple Repositories

End --url with /* to audit every repository of a GitHub user or organization, or every git repository in a local directory:

uvx repoauditorweb --url "https://github.com/<owner>/*" --pat <pat> --experience console --GitHub-include
uvx repoauditorweb --url "file:///<directory>/*" --experience json --CommunityStandards-include

The experience runs once for each repository, in name order, under an Auditing '<url>' (i of N)... heading; a failure while auditing one repository does not prevent the others from being audited. Modules that do not accept a url run only with the first repository.

* is only supported as the entire final path segment; partial wildcards (such as Repo*) are not supported. Quote the url so that the shell does not expand it.
Archived and forked GitHub repositories are excluded unless --include-archived or --include-forked is provided; these options are only valid with a GitHub url that ends with /*.
Without a PAT, GitHub only lists public repositories and limits requests to 60 per hour, so a warning is displayed.
A local directory's hidden subdirectories and subdirectories that are not git repositories are skipped.
The web experience opens a window for each repository in turn; provide --execute to run each audit without waiting for it to be invoked.

Experiences

Select the experience with --experience:

Experience	Description
`web` (default)	Opens a window to configure and execute the audit.
`console`	Executes the audit and writes the results to the terminal.
`json`	Executes the audit and writes the results to `stdout` as JSON; status information is written to `stderr`.

--execute runs the audit immediately in the web experience.

JSON Output

The json experience writes a single document with an entry for each audited repository. $schema references the JSON Schema for the document; its version is incremented whenever a change would break an existing consumer, and it is also included in the installed package.

{
  "$schema": "https://raw.githubusercontent.com/gt-csse/RepoAuditorWeb/main/src/RepoAuditorWeb/schemas/json_experience_v3.schema.json",
  "error": "<message or null>",
  "repositories": [
    {
      "arguments": {"<module name>": {"module": {}, "requirements": {"<requirement name>": {}}}},
      "common_arguments": {"url": "<url>", "pat": "*** or null", "branch": "<branch or null>"},
      "error": "<message or null>",
      "summary": {"skipped": 0, "does_not_apply": 0, "success": 0, "warning": 0, "error": 0, "total": 0},
      "results": [
        {
          "module": "<module name>",
          "requirement": "<requirement name>",
          "description": "<requirement description>",
          "result": "skipped | does_not_apply | success | warning | error",
          "context": "<Markdown or null>",
          "resolution": "<Markdown or null>",
          "rationale": "<Markdown or null>"
        }
      ]
    }
  ]
}

Once auditing begins, the document is valid however the run ends; a failure before auditing begins (such as an invalid wildcard url) is reported as an error and no document is written. The top-level error describes a failure that stopped the run (such as an interruption), in which case repositories contains the repositories audited before it; a repository's error describes a failure while auditing it, in which case its summary and results are null. The PAT is never included in the document.

Every result is included, not only failures. resolution and rationale are null when omitted via --no-resolution or --no-rationale.

Options

Every module and requirement contributes command line options; run repoauditorweb --help for the complete list. Common options include:

Option	Description
`--url`	The GitHub repository to audit; applied to every included module. The URL must begin with `https://`, `http://`, or `file://` (a local clone). The `GitHub` module requires the form `<server>/<owner>/<repository>`, where the owner and repository names contain only letters, digits, `-`, `_`, and `.`. End the url with `/*` to audit multiple repositories; see Auditing Multiple Repositories.
`--include-archived`, `--include-forked`	Include archived or forked repositories when a GitHub url ends with `/*`.
`--pat`	A GitHub Personal Access Token (PAT), or the path to a file containing only that token. Some requirements can only be evaluated with a PAT; see PAT Permissions.
`--branch`	The branch to evaluate; the default branch is used if not specified. The name must be a valid git branch name; for example, it cannot contain `..`, `@{`, whitespace, or any of `~^:?*[\`.
`--<Module>-include`	Include a module in the audit.
`--<Module>-<Requirement>-skip`	Skip a requirement.
`--evaluate-all`	Evaluate requirements that would otherwise be suppressed because a parent setting is not enabled.
`--no-resolution`, `--no-rationale`	Omit resolutions or rationales from the results.

--url, --pat, and --branch can also be provided through the environment variables REPO_AUDITOR_WEB_GITHUB_URL, REPO_AUDITOR_WEB_GITHUB_PAT, and REPO_AUDITOR_WEB_GITHUB_BRANCH. They apply to every module that uses them, so modules do not accept their own values for them. The web experience displays them in a Common section above the modules.

Configuration Files

--config loads option values from a YAML file, so that an audit configuration can be stored and shared. Keys are the option names without the leading --, with - replaced by _. Values provided on the command line take precedence over values in the file.

url: https://github.com/<owner>/<repo>
GitHub_include: true
GitHub_team_size: large
GitHub_DefaultBranch_value: [main, master]
CommunityStandards_include: true

uvx repoauditorweb --config audit.yaml

PAT Permissions

A GitHub Personal Access Token (PAT) is not required to audit public repositories, but GitHub only reports some settings to callers with elevated access. Requirements that cannot see a setting produce a warning without a PAT, and an error when the PAT lacks the necessary permissions.

Module	Data	Fine-grained token permission	Repository role
`GitHub`	Repository, branch, and ruleset information	`Metadata: Read`	Read
`GitHub`	Merge, auto-merge, branch deletion, and commit message settings	`Contents: Read and write`	Write
`GitHub`	Secret protection, push protection, and Dependabot security updates	`Administration: Read`	Admin
`GitHub`	Classic branch protection rules	`Administration: Read`	Admin
`CommunityStandards`, `JOSS`, `ScientificSoftware`	Repository contents (private repositories only)	`Contents: Read`	Read
`JOSS`	Repository, commit, and contributor information	`Metadata: Read`	Read

A fine-grained token must also list the audited repository among those it can access. A classic token requires the repo scope; the token's owner must still hold the repository role listed above.

Installation

Installation is not necessary when using uvx.

Installation Method	Command
Via uv	`uv add RepoAuditorWeb`
Via pip	`pip install RepoAuditorWeb`

Once installed, run repoauditorweb directly.

Verifying Signed Artifacts

Artifacts are signed and verified using py-minisign and the public key in the file ./minisign_key.pub.

To verify that an artifact is valid, visit the latest release and download the .minisign signature file that corresponds to the artifact, then run the following command, replacing <filename> with the name of the artifact to be verified:

uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>'); print('The file has been verified.')"

Development

Please visit Contributing and Development for information on contributing to this project.

Additional Information

Additional information can be found at these locations.

Title	Document	Description
Code of Conduct	CODE_OF_CONDUCT.md	Information about the norms, rules, and responsibilities we adhere to when participating in this open source community.
Contributing	CONTRIBUTING.md	Information about contributing to this project.
Custom Modules	docs/custom_modules.md	Information about defining custom modules in separate packages.
Development	DEVELOPMENT.md	Information about development activities involved in making changes to this project.
Governance	GOVERNANCE.md	Information about how this project is governed.
Maintainers	MAINTAINERS.md	Information about individuals who maintain this project.
Security	SECURITY.md	Information about how to privately report security issues associated with this project.

License

RepoAuditorWeb is licensed under the MIT license.

Metadata

Release files for repoauditorweb 0.71.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for repoauditorweb 0.71.2
File	Size	Uploaded
repoauditorweb-0.71.2.tar.gz	184.2 kB	Oct 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for repoauditorweb 0.71.2
File	Interpreter	ABI	Platform	Reset
repoauditorweb-0.71.2-py3-none-any.whl 286.9 kB Oct 15, 2026	Python 3	none	any	Details

Total release size: 471.1 kB

Release files / repoauditorweb-0.71.2.tar.gz

Download URL	repoauditorweb-0.71.2.tar.gz
Size	184.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`10f489b461715ec2e88b67c6fc850d00dff5d44e36f993bd7ee22d2c9533e20a`
BLAKE2b-256 checksum How to use checksums	`ba7b5baf3f7899d428fd2b85271233dfc7a059b38d0f2cffda84ac000e157c2d`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / repoauditorweb-0.71.2-py3-none-any.whl

Download URL	repoauditorweb-0.71.2-py3-none-any.whl
Size	286.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2b364c960da3d6f8800eed73a0e2a7f079028d26dcca9171c23ff1e740dea407`
BLAKE2b-256 checksum How to use checksums	`502e159a3c245246f0717c95e6f110caae9aa0b56b62f2d30b9c0d62616ef44d`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`