kubernetes/community: the governance repo behind the Kubernetes project

What kubernetes/community actually stores, and who needs it

The Kubernetes source tree and the Kubernetes community tree are separate repositories with separate purposes. This one is the community one. Its README describes it as "the starting point for joining and contributing to the Kubernetes community", and the top-level layout backs that up: governance.md, community-membership.md, code-of-conduct.md, a contributors/ directory, an elections/ directory, and one directory per Special Interest Group such as sig-cli, sig-network, sig-node and sig-release. There is also a committee-* set for the steering committee, the security response committee and the code of conduct committee.

The audience is narrow and specific. If you want to know which SIG owns a subsystem, when it meets, who leads it, or what the path to reviewer and approver status looks like, this repository is the record. If you are writing Kubernetes controllers or operators, you are in the wrong place: no Go packages for the API server live here, and the go.mod declares a single module named k8s.io/community whose dependencies are documentation tooling rather than Kubernetes itself.

The governance model is spelled out in three group types. Committees are chartered for sensitive topics and are allowed private communication. SIGs are persistent open groups that own subprojects, and the README states they "must have open and transparent proceedings". Working groups are temporary and cross SIG boundaries; the README is explicit that they "do not own any code or other long term artifacts" and report back through involved SIGs. That distinction matters when you are trying to find out who can actually approve a change.

The generator: why SIG READMEs are not hand-edited

The most consequential design decision in this repository is that a large part of the content is generated. The README points readers who want to change a SIG's meeting time or leads to the generator/ directory, which holds "instructions that detail how our docs are auto-generated". The Makefile confirms the mechanism: the default target runs generate, and generate runs a Go program.

The generator is not a documentation site builder. It reads structured data and writes Markdown. The go.mod file shows the ingredients: go-git for repository access, go-github for the GitHub API, gopkg.in/yaml.v3 for parsing, golang.org/x/mod, and k8s.io/enhancements. That combination suggests the generator pulls SIG metadata from YAML files and from GitHub, then rewrites the README files under the SIG directories. The Makefile also exposes reset-docs, which checks out sig-list.md, the sig-*/README.md files and the wg-*/README.md files from HEAD, a strong hint that generation overwrites exactly those paths and that a clean reset is the intended way to discard a bad run.

The practical consequence is a workflow rule: editing a generated README by hand is a losing move, because the next generate run will overwrite it. The README says so indirectly by directing SIG detail changes to the generator rather than to the SIG folder. The repository also carries a .generated_files entry at the top level, which is the kind of marker used to tell tooling which paths are machine-written. If you are preparing a pull request that touches a SIG README, expect reviewers to ask for the source data change instead.

Installing the toolchain and running make generate

There is no package to install and no binary to download. The repository is used by cloning it and running its Makefile, and the Makefile assumes Go is available on the host. The go.mod declares go 1.26.4, while the Makefile's container image is golang:1.22, a version mismatch worth noting before you pick a route.

Start by cloning and entering the repository, then run the generator through the default target:

make generate

That target runs go run ./generator/app.go, so the Go toolchain must be on your PATH. If you would rather not install Go locally, the Makefile provides a containerised path. It picks docker or podman automatically through the CONTAINER_ENGINE variable and mounts the working directory into the container:

make generate-containerized

After either command, the SIG README files and sig-list.md are rewritten. To see what changed, run git status and git diff. To throw the run away, use the reset target, which restores the checked-in versions of those files:

make reset-docs

Verification and tests are separate targets. make verify calls hack/verify.sh, and make test runs go test -v ./generator/..., so the test suite covers the generator rather than the documentation content. Both have containerised equivalents, verify-containerized and test-containerized, which take the same CONTAINER_ENGINE route.

Where the repository stops being the right tool

The first limitation is scope. Nothing here installs, configures or debugs a cluster. A reader arriving from a search for Kubernetes manifests, Helm charts or kubectl usage will find governance prose and SIG directories. The repository's own README routes technical readers elsewhere, to contributors/devel/README.md, which it describes as leading to "many relevant technical topics".

The second limitation is toolchain drift. The go.mod pins go 1.26.4 while the Makefile's IMAGE_NAME is golang:1.22. The containerised targets therefore run an older Go than the module declares, and the README does not document which of the two paths is authoritative. If a generate-containerized run fails on a language feature, the version gap is the first thing to check.

The third is that the generator depends on network services. go-github and k8s.io/enhancements are in the dependency list, and the enhancements module is pinned to a dated pseudo-version. A generator that talks to the GitHub API can be rate-limited or fail on authentication, and the Makefile passes only WHAT into the container as an environment variable. There is no documented offline mode, and the README does not describe rollback beyond the reset-docs target. If you need reproducible generation in a sandboxed CI runner, that is an open question you have to answer yourself.

Finally, contribution policy is not centralised. The README states that a SIG can have its own policy described in a README or CONTRIBUTING file in its folder, and it cites sig-cli/CONTRIBUTING.md as an example. So the top-level CONTRIBUTING.md is a starting point, not the whole rulebook.

How it differs from kubernetes/kubernetes and the enhancements repo

The obvious alternative is kubernetes/kubernetes, and the difference is categorical rather than incremental. That repository holds the code that runs clusters: the API server, controller manager, scheduler, kubelet and kubectl. This repository holds the human structure around that code. A change to scheduling behaviour goes there; a change to the scheduling SIG's charter, meeting notes or leadership goes here. Adopting one does not give you the other, and the two have entirely different review paths.

A closer alternative is k8s.io/enhancements, which appears in this repository's go.mod as a pinned dependency. Enhancements is where Kubernetes Enhancement Proposals live, meaning the design record for features that are being specified. The community repository is where the groups that review those proposals are defined. If your question is "what is the accepted design for this feature", enhancements is the target. If your question is "which group owns this area and how do I join it", this repository is the target. The dependency direction is one way: community imports enhancements, not the reverse, which tells you which repo is treated as downstream tooling.

For a documentation-only need, the repository's Markdown files are readable directly on GitHub or through the project's rendered site, and neither route requires cloning or running Go. The generator only pays off when you intend to change SIG metadata rather than read it.

Maintenance, licensing and what a fork commits you to

The repository is not archived, and its last push was on 2026-09-21. That is the current state of the main branch, and it is consistent with a governance repository that receives steady edits as SIG leadership and meeting schedules change.

Licensing is Apache-2.0, declared in the LICENSE file at the top level, with CLA.md alongside it. The Apache-2.0 terms cover the repository contents, but they say nothing about the separate contributor licence agreement that CLA.md describes, and nothing about the trademark rules that apply to using the Kubernetes name. If you plan to mirror this content or reuse the SIG directory structure in your own project's governance repo, the licence permits reuse of the text, while the CLA and any trademark policy are separate questions that the repository files raise but do not resolve. That is a boundary to check with whoever handles legal questions in your organisation, not something to infer from the LICENSE file alone.

The upgrade cost is low but not zero. There are no releases to track, so "upgrading" means pulling main and re-running make generate. The moving parts are the Go toolchain version, the pinned k8s.io/enhancements pseudo-version, and the generator's GitHub API calls. A fork that stops running generate will drift out of sync with the SIG metadata files, and the drift will not be visible until someone tries to regenerate.

Editorial conclusion

Adopt kubernetes/community if you need the authoritative record of how Kubernetes SIGs are organised, who leads them, or how to become a member, and you are willing to run the generator rather than hand-edit the generated files. Do not adopt it if you want Kubernetes source code (that lives elsewhere) or if you only need a one-off read of governance.md, in which case browsing the rendered site is enough. Before editing anything under a sig-* directory, check the README and CONTRIBUTING.md inside that SIG folder, because the top-level README states each SIG can set its own contribution policy, and run make generate afterwards to see which files the generator rewrites.

Frequently asked questions

Official sources

1. Issues
2. kubernetes/community on GitHub
3. License: Apache-2.0
4. README