README

orglinter

Lint GitHub organizations to ensure proper membership lists and configuration.

Installation

orglinter is designed to be installed with npm or yarn, either globally:

$ npm install -g orglinter
$ orglinter my-org-file.toml

Within your package:

$ npm install orglinter
$ npx orglinter my-org-file.toml

Or if you would like to make contributions to orglinter, using git and npm for local development:

$ git clone git@github.com:godaddy/orglinter.git
$ cd orglinter
$ npm install
$ npm start my-org-file.toml

Usage

A stub .env.dist file can be found for the convenience of users and developers at the root of this project. If you copy this file to .env and fill in the blanks, you should be good to go!

Running the script requires a single environment variable, which you can place into a .env file for automatic ingestion: GITHUB_TOKEN. This must be a personal access token generated by an existing organization owner, with the following permissions:

admin:org
read:user

Once a GITHUB_TOKEN is ready, the script can be run by npm start.

By default, the tool will look for a file at ./membership.toml. However you can also specify a different filename on the command line such as:

$ npm start my-org-file.toml

> orglinter@1.0.0 start
> node ./src/bin/cli.js
# ...

At the time of this writing, this script will be run manually after every change to the membership file. In the future, this will become an automatic execution in the CI pipeline, and will also be run on a regular basis to ensure that undocumented memberships do not exist, and that employees who have left the company are removed from the org.

Org Specification

All org data is stored in TOML files; one file representing one GitHub org. An example of such a file is provided as example.toml at the root of this project.

The relevant sections of this file are:

[org]

This contains configuration information about the org itself. Things such as the email address, Twitter username, and website URL. These values will all be verified against the actual org configuration and will raise an error if they do not match reality.

Additionally, the login key here is what is used to perform the actual org lookup.

[members]

This is the membership list for your org. The idea here is to map "internal" usernames (such as those found in an LDAP directory) to GitHub usernames. So assuming you have an "internal" username of adent, and a GitHub username of arthur_dent, you would add a line to this section like:

adent = "arthur_dent"

You can also tie multiple GitHub usernames to a single "internal" username by using a list. For example:

tmcmillan = ["trillian", "trillian_astra"]

[[teams]]

Each [[teams]] section is used, for now, primarily as a means of managing the admins of an org. In the future, this will manage actual GitHub teams. These are written as an array of tables. So one team would look like:

[[teams]]
name = "Heart of Gold Crew"
default_org_role = "ADMIN"
privacy = "SECRET"
members = ["mandroid", "tmcmillan", "zbeeblebrox"]

Note that the default_org_role = "ADMIN" is what marks the members of this team as org admins. And the names used in the members list are the "internal" usernames, rather than the GitHub usernames, of the individual members. This does have the side effect that, if an internal username is connected to multiple GitHub usernames, as demonstrated above, all of those GitHub usernames will be made admins of the org.

Development

Running Tests

This project uses mocha, assume, and sinon for its tests. It also uses [eslint] for ensuring code styling. Luckily, the execution of these tools is nicely automated for you. To run all of them, all you need to do is:

$ npm test

This will run all of the tests for you, followed by the linter.

Credits

Originally developed internally for making easier work of the management of GoDaddy's GitHub orgs. Primary authors at that time include:

Usage no npm install needed!