Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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.




Rule-based command-line tool for auditing guidelines in GitHub repositories







No packages published