gh-lint

Contents

• Install
• Usage
• Rules
  • Repo rules
  • Branch rules
  • Commit rules
  • PR rules
• Options
• Plugins
• License

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