0.11.0 • Public • Published


Greenkeeper badge Build Status npm version Coverage Status


Why gh-lint?

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.

See the talk about the development guidelines and gh-lint at FullStack 2017: video and slides.


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 rules

  • 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 rules

  • branch-default: check that default branch is master
  • branch-protection: check that master branch is protected

Commit rules

By default, these rules analyse the commits for the last 30 days. It can be changed using options --since and --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)

PR rules

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


  • -c (or --config) - configuration file location
  • -u (or --user) - GitHub username
  • -p (or --pass) - GitHub password
  • -t (or --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).
  • -a (or --after) / -b (or --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.
  • --since / --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.



Package Sidebar


npm i gh-lint

Weekly Downloads






Last publish


  • esp
  • mailonline