Merge pull request #2277 from cblecker/github-mgmt
GitHub Management Docs
This commit is contained in:
k8s-ci-robot
GitHub
commit
5fa7e3e6c0
4
CLA.md
4
CLA.md
|
|
@ -85,5 +85,5 @@ Someone from the CNCF will respond to your ticket to help.
|
|||
## Setting up the CNCF CLA check
|
||||
|
||||
If you are a Kubernetes GitHub organization or repo owner, and would like to setup
|
||||
the Linux Foundation CNCF CLA check for your repositories, please
|
||||
[read the docs on setting up the CNCF CLA check](/setting-up-cla-check.md)
|
||||
the Linux Foundation CNCF CLA check for your repositories, please
|
||||
[read the docs on setting up the CNCF CLA check](/github-management/setting-up-cla-check.md)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
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
|
||||
|
|
@ -1,7 +1,6 @@
|
|||
## Kubernetes Repositories
|
||||
## Kubernetes Repository Guidelines
|
||||
|
||||
|
||||
This document attempts to outline a structure for creating and associating github repositories with the Kubernetes project. It also describes how and when
|
||||
This document attempts to outline a structure for creating and associating GitHub repositories with the Kubernetes project. It also describes how and when
|
||||
repositories are removed.
|
||||
|
||||
The document presents a tiered system of repositories with increasingly strict requirements in an attempt to provide the right level of oversight and flexibility for a variety of different projects.
|
||||
|
|
@ -83,7 +82,7 @@ that our various projects and repositories are active and healthy. This
|
|||
ensures that repositories are kept up to date with the latest Kubernetes
|
||||
wide processes, it ensures a rapid response to potential required fixes
|
||||
(e.g. critical security problems) and (most importantly) it ensures that
|
||||
contributors and users receive quick feedback on their issues and
|
||||
contributors and users receive quick feedback on their issues and
|
||||
contributions.
|
||||
|
||||
#### Grounds for removal
|
||||
|
|
@ -91,7 +90,7 @@ SIG repositories and core repositories may be removed from the project if they
|
|||
are deemed _inactive_. Inactive repositories are those that meet any of the
|
||||
following criteria:
|
||||
|
||||
* There are no longer any active maintainers for the project and no
|
||||
* There are no longer any active maintainers for the project and no
|
||||
replacements can be found.
|
||||
* All PRs or Issues have gone un-addressed for longer than six months.
|
||||
* There have been no new commits or other changes in more than a year.
|
||||
|
|
@ -102,8 +101,8 @@ circumstances (e.g. a code of conduct violation).
|
|||
|
||||
|
||||
#### Procedure for removal
|
||||
When a repository is set for removal, it is moved into the
|
||||
[kubernetes-retired](https://github.com/kubernetes-retired) organization.
|
||||
When a repository is set for removal, it is moved into the
|
||||
[kubernetes-retired](https://github.com/kubernetes-retired) organization.
|
||||
This maintains the
|
||||
complete record of issues, PRs and other contributions, but makes it clear
|
||||
that the repository should be considered archival, not active. We will also
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Kubernetes Github Organization Guide
|
||||
# Kubernetes GitHub Organization Guide
|
||||
|
||||
The Kubernetes project leverages multiple GitHub organizations to store and
|
||||
organize code. This guide contains the details on how to run those organizations
|
||||
|
|
@ -26,40 +26,6 @@ contact the steering committee and CNCF prior to moving any code in.
|
|||
It is easier to start new code in a Kubernetes organization than it is to
|
||||
transfer in existing code.
|
||||
|
||||
## Current Organizations In Use
|
||||
|
||||
The following organizations are currently known to be part of the Kubernetes
|
||||
project:
|
||||
|
||||
### Actively used GitHub Organizations:
|
||||
* [kubernetes](https://github.com/kubernetes)
|
||||
* [kubernetes-client](https://github.com/kubernetes-client)
|
||||
* [kubernetes-csi](https://github.com/kubernetes-csi)
|
||||
* [kubernetes-incubator](https://github.com/kubernetes-incubator)
|
||||
* [kubernetes-retired](https://github.com/kubernetes-retired)
|
||||
* [kubernetes-security](https://github.com/kubernetes-security)
|
||||
* [kubernetes-sig-testing](https://github.com/kubernetes-sig-testing)
|
||||
* [kubernetes-sigs](https://github.com/kubernetes-sigs)
|
||||
|
||||
### Non-actively used GitHub Organizations:
|
||||
* [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-incubator-retired](https://github.com/kubernetes-incubator-retired)
|
||||
* [kubernetes-providers](https://github.com/kubernetes-providers)
|
||||
* [kubernetes-sidecars](https://github.com/kubernetes-sidecars)
|
||||
* [kubernetes-test](https://github.com/kubernetes-test)
|
||||
* [kubernetes-tools](https://github.com/kubernetes-tools)
|
||||
|
||||
† kubernetes-retired should be used instead of kubernetes-graveyard going forward.
|
||||
|
||||
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).
|
||||
|
||||
## Team Guidance
|
||||
|
||||
Each organization should have the following teams:
|
||||
|
|
@ -93,4 +59,4 @@ for all orgs going forward. Notable discrepancies at the moment:
|
|||
|
||||
Repositories have additional guidelines and requirements, such as the use of
|
||||
CLA checking on all contributions. For more details on those please see the
|
||||
[Kubernetes Template Project](https://github.com/kubernetes/kubernetes-template-project).
|
||||
[Kubernetes Template Project](https://github.com/kubernetes/kubernetes-template-project), and the [Repository Guidelines](kubernetes-repositories.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/
|
||||
|
|
@ -13,7 +13,7 @@ the Linux Foundation CNCF CLA check for your repositories, please read on.
|
|||
- Payload URL: https://identity.linuxfoundation.org/lfcla/github/postreceive?group=284&comment=no&target=https://identity.linuxfoundation.org/projects/cncf
|
||||
- `group=284` specifies the ID of the CNCF project authorized committers group in our CLA system.
|
||||
- `comment=no` specifies that our system should not post help comments into the pull request (since the Kubernetes mungebot does this).
|
||||
- `target=https://identity.linuxfoundation.org/projects/cncf` specifies what will be used for the "Details" link in Github for this status check.
|
||||
- `target=https://identity.linuxfoundation.org/projects/cncf` specifies what will be used for the "Details" link in GitHub for this status check.
|
||||
- Content Type: 'application/json'
|
||||
- Secret: Please contact [@idvoretskyi](mailto:ihor@cncf.io), and [@caniszczyk](mailto:caniszczyk@linuxfoundation.org).
|
||||
- Events: Let me select individual events
|
||||
|
|
@ -56,5 +56,5 @@ the same org/repo, to ensure that it can add labels `cncf-cla: yes` and `cncf-cl
|
|||
on the status published by the Linux Foundation webhook.
|
||||
|
||||
The label automation may not be essential for your repository, if you’re not using merge
|
||||
automation. For repos with maintainers doing manual merges, github protected branches may
|
||||
automation. For repos with maintainers doing manual merges, GitHub protected branches may
|
||||
suffice.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# IMPORTANT - The Kubernetes Incubator process is now deprecated and has been superseded by Kubernetes subprojects
|
||||
|
||||
For information on creating a repository for a subproject see: [kubernetes-repositories](kubernetes-repositories.md)
|
||||
For information on creating a repository for a subproject see: [kubernetes-repositories](/github-management/kubernetes-repositories.md)
|
||||
|
||||
Each SIG should define the process for sponsoring new subprojects in its charter. For information on SIG governance
|
||||
and charters see: [SIG governance](committee-steering/governance/README.md)
|
||||
|
|
|
|||
Loading…
Reference in New Issue