GitHub Management Docs #2277
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| # GitHub Management | ||
|
|
||
| The Kubernetes project uses Github extensively to store and organize code, | ||
| manage issues and documentation, and provide a consistent contributor flow. | ||
|
|
||
| With the size and growth of the Kubernetes project, management of our Github | ||
| footprint has historically been a challenge. We have created a number of | ||
| policies to reduce friction and ease administration of our Github repositories | ||
| and organizations. We have also created a number of tools to automate setup and | ||
| enforcement of these policies. | ||
|
|
||
| ## Guides | ||
| - [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 | ||
|
|
||
| The following organizations are currently known to be part of the Kubernetes | ||
| project | ||
|
|
||
| ### Actively used GitHub Organizations | ||
|
|
||
| | Name | Description | | ||
| | :--: | :---------: | | ||
| | [kubernetes](https://github.com/kubernetes) | Core | | ||
| | [kubernetes-client](https://github.com/kubernetes-client) | API Client Libraries | | ||
| | [kubernetes-csi](https://github.com/kubernetes-csi) | Container Storage Interface Components | | ||
| | [kubernetes-incubator](https://github.com/kubernetes-incubator) | Legacy Incubator Projects | | ||
| | [kubernetes-retired](https://github.com/kubernetes-retired) | Retired/Archived Projects | | ||
| | [kubernetes-security](https://github.com/kubernetes-security) | Private Security Fix Mirror | | ||
| | [kubernetes-sigs](https://github.com/kubernetes-sigs) | SIG-related Projects | | ||
|
|
||
| ### Non-actively used GitHub Organizations | ||
|
|
||
| | Name | Description | | ||
| | :--: | :---------: | | ||
| | [kubernetes-addons](https://github.com/kubernetes-addons) | | | ||
| | [kubernetes-charts](https://github.com/kubernetes-charts) | | | ||
| | [kubernetes-extensions](https://github.com/kubernetes-extensions) | | | ||
| | [kubernetes-federation](https://github.com/kubernetes-federation) | | | ||
| | [kubernetes-graveyard](https://github.com/kubernetes-graveyard) | kubernetes-retired should be used instead going forward | | ||
| | [kubernetes-incubator-retired](https://github.com/kubernetes-incubator-retired) | kubernetes-retired should be used instead going forward | | ||
| | [kubernetes-providers](https://github.com/kubernetes-providers) | | | ||
| | [kubernetes-sidecars](https://github.com/kubernetes-sidecars) | | | ||
| | [kubernetes-sig-testing](https://github.com/kubernetes-sig-testing) | | | ||
| | [kubernetes-test](https://github.com/kubernetes-test) | | | ||
| | [kubernetes-tools](https://github.com/kubernetes-tools) | | | ||
|
|
||
| Note, this list is subject to change. | ||
|
|
||
| There are more organization names that we are squatting on with possible future | ||
| intentions. [For more details please see community issue #1407](https://github.com/kubernetes/community/issues/1407). | ||
|
|
||
| ## Tooling | ||
|
There was a problem hiding this comment. Don't want to call out prow/tide? The plugins and bot commands that we use are not obvious |
||
|
|
||
| We have created a number of tools to help with the management of or Github | ||
| repositories and organizations: | ||
| - [prow](https://git.k8s.io/test-infra/prow): Prow is our system for handling | ||
| GitHub events and commands for Kubernetes. It is comprised of a number of | ||
| modules/plugins. A couple key ones for GitHub management are below, but a full | ||
| list of commands is available [here](https://go.k8s.io/bot-commands) | ||
| - [branchprotector](https://git.k8s.io/test-infra/prow/cmd/branchprotector): | ||
| enforce branch protection settings across an organization | ||
| - [peribolos](https://git.k8s.io/test-infra/prow/cmd/peribolos): Manage Github | ||
| organization and team membership based on a defined YAML configuration | ||
| - [label_sync](https://git.k8s.io/test-infra/label_sync): Add, modify, delete, | ||
| and migrate labels across an entire organization based on a defined YAML | ||
| configuration | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this still active? Don't we want to suggest kubernetes-sigs (subprojects) instead?
https://github.com/kubernetes/community/blob/master/incubator.md
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's still active in that there are still repos there, and the steering committee isn't pushing them to migrate anywhere right now. If it's in incubator, it can stay there for the time being, but no new projects will be added.