When you agree on some development guidelines, you need to know when they are not followed.
Most major open-source projects have adopted some automation to validate contribution guidelines. With gh-lint you can validate guidelines in public and private repositories across multiple organisations using pre-defined and custom rules.
npm install -g gh-lint
ghlint -c config.json -u $GITHUB_USERNAME -p $GITHUB_TOKEN
where config.json is a configuration file described by this schema.
You can define rules for organisations, teams and specific repos.
gh-lint can generate output in TAP format (with option
--tap) that can be consumed by tap-github-issues to open, close and update issues in the GitHub repositories where the rules are checked.
See gh-lint-demo for the example configuration and the scripts to run gh-lint and tap-github-issues.
- repo-description: check that repo has description specified in GitHub UI
- repo-homepage: check that repo has homepage specified in GitHub UI
- repo-readme: check that repo has README file
- repo-team: check that repo is assigned to one of specified teams
- repo-admin-team: check repo admin team(s)
- branch-default: check that default branch is master
- branch-protection: check that master branch is protected
By default, these rules analyse the commits for the last 30 days. It can be changed using options
--until (see below).
- commit-name: check that commit names satisfy semantic commit conventions
- commit-pr: check that commit was added to master via PR
- commit-user: check that commit is associated with some GitHub user(s)
By default, these rules analyse the PRs for the last 30 days. It can be changed using option
--since (see below).
- pr-review: check that all PRs have at least one review that approved them
--config) - configuration file location
--user) - GitHub username
--pass) - GitHub password
--team-permission) - minimal team permission level required for repo to be associated with the team (for team-specific rules). The default is "admin". Other values are "push" (includes admin access) and "pull" (repo will be associated with the team that has any access level).
--before) - only validate repositories in organizations and in teams that were changed after/before this date (also can be date-time or the integer number of days). These options have no effect on repositories that are explicitely specified.
--until- validate commits since/until this date (also can be date-time or the integer number of days)
--tap- output results in TAP format
Rules can be defined in external modules.
The package name must be prefixed with "ghlint-plugin-". In the configuration file a plugin name can be used with or without this prefix.
A plugin package should export an object with a single property "rules" that has a map of rule definitions. Each rule should be valid according to the rule schema.