Add GitHub Permissions doc

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/