Lint GitHub organizations to ensure proper membership lists and configuration.
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 [email protected]:godaddy/orglinter.git
$ cd orglinter
$ npm install
$ npm start my-org-file.toml
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
> [email protected] 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.
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:
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.
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"]
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.
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.
Originally developed internally for making easier work of the management of GoDaddy's GitHub orgs. Primary authors at that time include: