diff options
| -rw-r--r-- | github-management/README.md | 1 | ||||
| -rw-r--r-- | github-management/permissions.md | 101 |
2 files changed, 102 insertions, 0 deletions
diff --git a/github-management/README.md b/github-management/README.md index 87f9640f..9284fe78 100644 --- a/github-management/README.md +++ b/github-management/README.md @@ -13,6 +13,7 @@ enforcement of these policies. - [Organization Owners Guide](org-owners-guide.md) - [Repository Creation Guidelines](kubernetes-repositories.md) - [Setting up the CNCF CLA Check](setting-up-cla-check.md) +- [GitHub Permissions](permissions.md) ## Project Owned Organizations diff --git a/github-management/permissions.md b/github-management/permissions.md new file mode 100644 index 00000000..3ae03c70 --- /dev/null +++ b/github-management/permissions.md @@ -0,0 +1,101 @@ +# GitHub Permissions + +GitHub provides a limited permissions model for organizations and repositories. +It lacks granularity, and for the most part is "all or nothing". This doesn't +scale well with the size and velocity of the Kubernetes project. + +We have created a number of automated systems/bots to allow us to work around +these limitations. Authorized users can issue [bot commands] to execute actions +against PRs and issues without having direct GitHub access to run these +actions. [OWNERS] files are used to gate approvals to merge, and most merges are +handled by automation. This allows us the flexibility to delegate access to +small or large groups of users, without providing direct write or admin access. + +That said, there are some actions that are so infrequent, or so complex that +automation isn't a good fit. There is also a need for a small set of users that +can act as a backstop for setting up and maintaining this automation, and +manual intervention if needed. + +## Organization Level Permissions + +GitHub provides [two access levels][org permissions] to an organization: owner, +and member. + +### Owner + +Organization owners have full access to the organization, including the ability +to modify billing information and even delete the entire organization. +Therefore, we are very cautious about giving more people this access than +really need it. + +There are certain actions that require org owner access: +- Invite or remove members from the organization (in future, will be handled by + [peribolos]) +- Access the organization audit log +- Create new repositories +- Transfer repositories +- Approve GitHub application integrations + +**// TODO(cblecker):** Define specific roles that need this. + +### Member + +Organization members are granted "read" access to all repositories in the org, +are able to be assigned issues and PRs, and are able to mention and join +teams. This is the base level of access to an organization. + +A our automation tools look for organization membership as a permissions level +for running certain bot commands. The [bot commands] list details which +commands are restricted to org members. + +Org membership is granted as a part of becoming a member of the Kubernetes +community as defined in the [community membership] document. + +## Repository Level Permissions + +GitHub provides [three access levels][repo permissions] to a repository: admin, +write, and read. + +### Admin + +A repository admin has full access to the repository, and is able to modify any +repository-scoped setting, including renaming or deleting a repository, +manually merge code, and override/change branch protection settings. This is a +trusted role, and should only be given to a limited number of senior +maintainers of a repository. + +In most cases, this level of access should not be necessary as the majority of +actions will be able to be implemented by automation. Certain actions like +creating a release may still need this level of access. + +**// TODO(cblecker):** Define specific roles that need this. + +### Write + +Providing direct write access to a repository exposes a number of settings that +are not normally available, including: +- The ability to manually add and remove labels from issues/PRs +- The ability to push new branches +- Manually open and close issues/PRs + +While users with write access cannot override branch protection settings and +manually merge PRs, they can manually apply labels like `lgtm`/`approve`, +bypassing normal processes. Write access is being phased out as the majority +of actions are implemented via automation. + +### Read + +This is the default level of access that is provided to org members on every +repo in the organization. Read access allows you to be assigned issues and PRs +in the repository, but that's about it. It is provided by default to every +member in the organization. + + +[bot commands]: https://go.k8s.io/bot-commands +[community membership]: /community-membership.md +[org permissions]: +https://help.github.com/articles/permission-levels-for-an-organization/ +[OWNERS]: /contributors/guide/owners.md +[peribolos]: https://git.k8s.io/test-infra/prow/cmd/peribolos +[repo permissions]: +https://help.github.com/articles/repository-permission-levels-for-an-organization/ |