Rule-based command-line tool for auditing guidelines in GitHub repositories
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
schemas
spec
.eslintrc.yml
.gitignore
.travis.yml
LICENSE
README.md
package.json

README.md

gh-lint

Greenkeeper badge Build Status npm version Coverage Status

Contents

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.

Install

npm install -g gh-lint

Usage

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.

Rules

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

Options

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

Plugins

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.

License

MIT