I would like some feedback from developers on how best to organize permissions within the GitHub organizations of the Fiji software stack. If you do not (want to) know how GitHub teams and permissions work, please ignore this thread!
The orgs under discussion are
scijava, and perhaps
fiji-BIG. These orgs do not necessarily all need to employ exactly the same pattern of permissions, but right now the situation is an inconsistent hodge-podge.
I see three major requirements for managing permissions:
- Security. This means “deny by default” and only granting direct push access to people when they really need it (by some definition of “need”; see below).
- Community. We want management of these orgs to scale beyond a single bottleneck or gatekeeper. Trusted people should be able to add more trusted people.
- Ease of administration. Having only a single team for each org, with admin access for all repositories, would maximally solve this requirement—but at the expense of security.
To balance these, we need to know our development workflow. How much do we want to encourage/enforce use of PRs, versus direct pushes?
- One approach is to lock down all repos completely, with everyone using fork-and-pull always. This is e.g. how the OME team does things.
- Another way is to grant anyone doing active+regular work on a component push access to that component, so that they can push topic branches directly. Before GitHub, this was certainly needed, and historically is how the Fiji project has done things.
- A middle ground exists, where pushing to master is not allowed, but pushing topic branches to official repos is allowed (from which PRs can be filed).
The always-fork-and-pull workflow has pros and cons:
- [Pro] All work has an associated issue with discussion thread. This could be useful for the changelogs (see discussion).
- [Con] Work can get bogged down and out of sync awaiting review.
- [Pro+Con] Topic branches are organized by who is working on them. This avoids a huge overgrown list of topic branches in the official repo, but can make it harder to browse what is being worked on across all developers. Permissions are an obstacle when multiple people collaborate on a PR.
To help think clearly who should have which permissions technically, here is an enumeration of SciJava team roles:
- Founder - Created the project. Does not imply any current participation or responsibility.
- Lead - Has decision-making authority: timing of releases, inclusion of features, etc.
- Developer - Adds new features or enhancements. Can be assigned to address feature requests.
- Debugger - Fixes bugs. Can be assigned open issues to solve.
- Reviewer - Reviews patch submissions.
- Support - Responds to community questions and issue reports. Keeps the issue tracker organized.
- Maintainer - Merges patch submissions. Cuts releases.
- Contributor - Contributed code to the project. Does not imply any current participation or responsibility.
Note that these are per-component roles.
How GitHub does permissions
GitHub supports the following per-repository permissions:
- Read. Can clone and fork. Since we are OSS, there is no need to grant this permission explicitly since everything is already world-readable.
- Write. I.e. push access. Typically all/any branch, although it is possible to impose restrictions as discussed above. Also includes full power over the issue tracker.
- Maintain. Can manage permissions of others, edit description and URL, and other non-destructive actions.
- Admin. Full control, including the ability to rename or move the repo, archive/unarchive, and delete the repository.
It is possible to, for each repository, add each individual as a separate collaborator with one of the above permission levels.
But in addition, GitHub supports teams on the organization level, each of which is a list of users plus a list of (repository, permission level) pairs. The purpose is to label a list of users and assign everyone on that list the same permission levels for a particular list of repositories. This makes it more convenient to add/remove users from many related repositories at once. For example, as of this writing, the
polyglot team of
imagej grants several people admin access to several repositories related to packaging and cross-language support (chocolatey-packages, imagej-electron-app, imagej-itk, imagej-launcher, imagej-matlab, imagej-node, imagej-notebook, imagej-server, pyimagej, tutorials).
Finally, GitHub has the notion of organization owners who have admin access to everything in the organization, as well as the ability to create new repositories.
See Managing access to your organization’s repositories for more on GitHub’s permissions.
Expressing SciJava team roles using GitHub permissions
So a key question is: for each SciJava team role, how best to express that technically in GitHub terms?
First, we need a (IMHO straightforward) mapping from team roles to GitHub permissions:
- Founder - N/A—not a participatory role.
- Lead - Maintain.
- Developer - Write.
- Debugger - Write.
- Reviewer - Write.
- Support - Write. (For the issue tracker.)
- Maintainer - Maintain.
- Contributor - None—use PRs.
Next, we need to decide how best to use GitHub’s available permission tools to achieve and maintain this mapping for each repository.
The way I am leaning right now is to use the collaborator mechanism to manage every repository completely separately, and avoid organization-wide teams whenever possible. One issue with that is that we have hundreds of repositories, so I’ll need to write a script to scrape each project POM and validate the corresponding GitHub permissions configuration. I am hoping the GitHub API is powerful enough to support doing that, because I really don’t want to manually click into each and every repository by hand.
This will hopefully help encourage the team role metadata in POMs to more closely match the reality of what people are working on.
For “blanket maintainers” like myself, I think it is sufficient to use GitHub’s owner mechanism. However, we want to keep the number of owners low.
- Do you support my plan to get rid of teams in favor of the above mapping?
- Given our structure, does anyone see any use for GitHub teams?
- Do you favor imposing a always-fork-and-pull model of development?
- Do you favor imposing a no-direct-pushes-to-master-ever restriction?
- What do you think is a good number of owners per org to avoid a too-low bus factor? 3? 5?
- Other thoughts and opinions?