permissions

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 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 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.