{"id":19259236,"url":"https://github.com/concourse/governance","last_synced_at":"2025-11-11T22:30:21.179Z","repository":{"id":38019389,"uuid":"345783579","full_name":"concourse/governance","owner":"concourse","description":"Documentation and automation for the Concourse project governance model.","archived":false,"fork":false,"pushed_at":"2025-01-17T21:49:00.000Z","size":280,"stargazers_count":72,"open_issues_count":1,"forks_count":59,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-02-12T02:25:28.681Z","etag":null,"topics":["governance"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/concourse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-08T20:19:19.000Z","updated_at":"2025-01-17T21:49:00.000Z","dependencies_parsed_at":"2023-02-17T14:45:52.742Z","dependency_job_id":"c6bd00b8-05af-40de-8c2a-99ec0b17dbd4","html_url":"https://github.com/concourse/governance","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fgovernance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fgovernance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fgovernance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fgovernance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/concourse","download_url":"https://codeload.github.com/concourse/governance/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239592976,"owners_count":19664858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["governance"],"created_at":"2024-11-09T19:15:49.579Z","updated_at":"2025-11-11T22:30:21.142Z","avatar_url":"https://github.com/concourse.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Concourse Governance (Archived)\n\n**Concourse is joining the Cloud Foundry Foundation. They have their own mechanics for org governance that we are going to use instead.**\n\n---\n\nThis document outlines a set of policies in order to provide a level playing\nfield and open process for contributors to join the Concourse project.\n\nIn addition to this document, this repository contains live configuration for\nthe state of the Concourse GitHub organization. All configuration is\nautomatically applied via [Terraform][terraform] and synchronized daily to\nprevent drift.\n\n[terraform]: https://www.terraform.io/\n\n## Governance Model\n\nIndividual contributors to the Concourse project can become members of\n**teams**, each with a stated purpose, a clear set of responsibilities, and a\nlist of repos that they maintain.\n\nTeams collaborate through discussions on GitHub and propose changes through\npull requests that may cross team boundaries.\n\nIdeally, teams should be split along boundaries that enhance the focus given to\ndifferent facets of the Concourse project. Repositories should typically belong\nto a single team in order to encourage advocacy for different facets through\ncollaboration.\n\nFor example:\n\n* the [**core** team](teams/core.yml) has authority over the [RFC\n  process][rfcs-repo] and associated design principles, but cannot directly\n  push to the the [Concourse repo][concourse-repo].\n* the [**maintainers** team](teams/maintainers.yml) has authority over the\n  [Concourse repo][concourse-repo] and submits RFCs to develop a roadmap that\n  aligns with Concourse's core design principles.\n* the **core** team engages with the **maintainers** team to ensure new\n  proposals do not introduce unnecessary risk or become a maintenance burden.\n* the **maintainers** team then guides the planning and implementation of the\n  proposal through pull requests to the Concourse repo.\n\nTeams may split off from larger teams as more of these boundaries are\ndiscovered. Careful attention should be paid to teams with too many\nresponsibilities - there may be significant facets being neglected.\n\n[rfcs-repo]: https://github.com/concourse/rfcs\n[concourse-repo]: https://github.com/concourse/concourse\n\n\n### Individual Contributors\n\nIndividual contributors are listed under `./contributors`. Pull requests will\nbe reviewed by members of the **community** team. Feel free to submit one at\nany time!\n\nThe name of the file should match your github handle. Each\n`./contributors/*.yml` file has the following fields:\n\n* `name` - the contributor's real name, or an alias if they would rather not\n  share.\n* `github` - the contributor's GitHub login\n* `discord` - the contributor's Discord username + number, e.g. `foo#123`\n* `repos` - map from repo name to permission to grant for the user. this should\n  only be used for bot accounts; in general repo permissions should be done\n  through teams.\n\nEach contributor will be granted membership of the Concourse GitHub\norganization. This does not grant much on its own; repository access for\nexample is determined through teams.\n\n\u003e Note: the Discord attribute is not used at the moment, but it may be helpful\n\u003e in the future to have someplace that correlates these different identities.\n\n\n\n### Teams\n\nTeams are listed under `./teams`. Pull requests will be reviewed by the\n**community** team, who will further request reviews from all affected teams or\nindividuals. (This can probably be automated at some point.)\n\nEach `./teams/*.yml` file has the following fields:\n\n* `name` - a name for the team, stylized in lowercase.\n* `purpose` - a brief description of the team's focus.\n* `responsibilities` - a list of the team's discrete responsibilities, or a\n  link to where they can be found.\n* `members` - a list of contributors to add to the team, e.g. `foo` for\n  `./contributors/foo.yml`.\n* `repos` - a list of GitHub repositories for the team to be added to.\n\nEach team must have a stated purpose summarizing its goals.\n\nEach team is also responsible for maintaining a list of its responsibilities.\n(No need to list that one.) Doing so clarifies the scope of a team for\nnewcomers and makes it easier to tell when a team is overloaded and could\nbenefit from being divided or reorganized.\n\nEach team lists its members which correspond to filenames under\n`./contributors` (without the `.yml`).\n\nEach team lists GitHub repositories for which the team will be granted\nthe [Maintain permission][permissions].\n\nEach team is responsible for determining the best way for the team to operate,\nthough it is strongly encouraged that each team work in the open, either on\nGitHub or somewhere easy to access, to the extent that doing so is beneficial\nto the team and to the community. (For example, teams may choose to use a\nprivate discussion area to handle sensitive matters.)\n\nSuggestion: team processes can be defined in a new repository managed\nexclusively by the team. The team repository can be created via submitting a PR\nto this repo. See [Repositories](#repositories).\n\n#### Voting\n\nDecisions are reached through consensus among the team members through a 66%+\nsupermajority unless stated otherwise through the team's own processes.\n(Implementation of said process would require a 66% supermajority.)\n\nVoting can be expressed through pull request review, leaving a comment, or\nthrough some other form of record - ideally permanent.\n\nTeams are not required to have designated leaders. Teams may choose to\ndesignate a leader and define their role and responsibilities through a vote\namongst the team.\n\n[permissions]: https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization\n\n#### Joining a Team\n\nTo propose the addition of a team member (either yourself or on behalf of\nsomeone else), submit a PR that adds them as a contributor (if needed) and\nlists them as a member of the desired team.\n\nPull requests that add someone to a team require enough approving reviewers to\npass the [voting process](#voting). The **community** team member reviewing the\npull request is responsible for determining the number of required votes based\non the destination team's size and voting process, and they will merge the PR\nwhen the necessary votes have been acquired, or close the PR if the necessary\nvotes cannot be reached. (Note: there's room for human error here; ideally this\nwould be automated, but until then please assist by leaving a comment if\nanything is wrong.)\n\nThere are no specific qualifications for joining a team outlined by the\ngovernance model itself; gaining an approving vote may be entirely subjective\nand the barrier to entry will vary from team to team. As a general rule,\napplications with no prior context or trust to build upon will almost certainly\nbe rejected.\n\n\n#### Leaving a team\n\nA team member may choose to leave their team at any time by submitting a PR\nthat removes themself from the list of members. A vote is not necessary for\nvoluntarily leaving a team.\n\nTo remove someone *else* from the team, submit a PR as above and it will go\nthrough the same voting process as joining. The member being removed may also\nvote.\n\n\n#### Creating a new Team\n\nNew teams may be formed at any time by submitting a PR. A team with only one\nmember is probably not a good sign, so try to recruit folks during this stage.\n\nIf a new team is being created to split off from a larger team, you will have\nto negotiate ownership of the relevant repos and ideally move them entirely to\nthe new team. This will obviously require approval from the original team.\n\n\n### Repositories\n\nRepositories are listed under `./repos`. Pull requests will be reviewed by the\n**infrastructure** team.\n\nEach `./repos/*.yml` file has the following fields:\n\n* `name` - a name for the repository.\n* `description` - a description for the repository.\n* `topics` - topics to set for the repository.\n* `homepage_url` - a website (if any) associated to the repository.\n* `has_issues` - whether the repository has Issues enabled (default `false`).\n* `has_projects` - whether the repository has Projects enabled (default\n  `false`).\n* `has_wiki` - whether the repository has the Wiki enabled (default `false`).\n* `has_discussions ` - whether the repository has the Discussions enabled (default `false`).\n* `pages` - GitHub pages configuration:\n  * `branch` - the branch to build.\n  * `path` - the path to serve (default `/`).\n  * `cname` - an optional CNAME to set for the website.\n* `branch_protection` - a list of branch protection settings:\n  * `pattern` - branch name pattern to match.\n  * `allows_deletions` - whether the branches can be deleted.\n  * `required_checks` - required status checks for PRs to be merged.\n  * `strict_checks` - require branches to be up-to-date before merging.\n  * `required_reviews` - number of approved reviews required for PRs to be\n    merged.\n  * `dismiss_stale_reviews` - dismiss reviews when new commits are pushed.\n  * `require_code_owner_reviews` - require approval from code owners for PRs\n    which affect files with designated owners.\n* `deploy_keys` - a list of [deploy keys] to add to the repo\n  * `title` - a title for the key\n  * `public_key` - the public key\n  * `writable` - whether the key can push to the repo\n\nAll repositories have [vulnerability alerts] enabled.\n\nAll repositories are configured to [delete branches] once their PR is merged.\n\nAll repositories will be archived upon deletion from this repo (instead of\nbeing deleted). Permanent deletion must be done manually by a member of the\n**infrastructure** team.\n\n[vulnerability alerts]: https://docs.github.com/en/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies\n[delete branches]: https://docs.github.com/en/github/administering-a-repository/managing-the-automatic-deletion-of-branches\n[deploy keys]: https://docs.github.com/en/developers/overview/managing-deploy-keys\n\n\n## Amending the Governance Model\n\n\u003e Frankly, I am more used to solving computer problems than human problems, so\n\u003e this process may be naive, it may feel too rigid, or it may feel completely\n\u003e ambiguous. Nothing here is set in stone. Please improve it as necessary and\n\u003e remove this disclaimer once we feel more confident. - **@vito**\n\nPull requests to this process (`README.md`) will be reviewed by the\n**core** team.\n\n\n## Enforcing the Governance Model\n\nThe configuration in this repository is applied automatically via Terraform.\n\nIn addition to the Terraform configuration, the state of the entire GitHub\norganization can be tested against the desired state via `go test`. This test\nsuite will also detect any 'extra' configuration like untracked repositories,\nunknown teams, and extra repository collaborators.\n\n\n### Applying Changes\n\nTo apply these changes you must be an Owner of the Concourse GitHub\norganization.\n\nSet the `github_token` var and run `terraform apply`:\n\n```sh\n$ terraform init # once\n$ echo '{\"github_token\":\"...\"}' \u003e .auto.tfvars.json\n$ terraform apply\n```\n\nThis token must have *admin:org* and *repo* scopes.\n\n\n### Testing Actual vs. Desired State\n\nTests are included which will verify that all permissions in the relevant\nservices reflect the configuration in the repository.\n\nRunning the tests requires a `$GITHUB_TOKEN` to be set.\n\n```sh\n$ export GITHUB_TOKEN=\"$(jq -r .github_token .auto.tfvars.json)\"\n$ go test\n```\n\nTest failures must be addressed immediately as they may indicate abuse, though\nlaziness or ignorance of this process is more likely.\n\n\n### GitHub Organization Settings\n\nThis governance model requires that organization members have extremely limited\n[privileges][member-privileges]. Unfortunately these can't currently be set by\nTerraform, so I'm documenting them here for good measure.\n\nThe following settings are required for any of this to make sense:\n\n* **Base permissions** must be \"None\" so that organization membership does not\n  grant visibility of private repositories (if any exist) and repository\n  access is determined exclusively through teams.\n* **Repository creation** and **Pages creation** must be disabled for both\n  Public and Private so that all repository management shall be done through\n  this repo.\n* **Allow members to create teams** must be disabled so that all team\n  administration shall be done through this repo.\n\nAdditionally, repository admin permissions should be restricted. No team will\never be an 'admin' at the repo level, so this should never come up, but we can\nprevent further damage if someone does manage to escalate:\n\n* **Allow members to change repository visibilities for this organization**\n  should be disabled.\n* **Allow members to delete or transfer repositories for this organization**\n  should be disabled.\n* **Allow members to delete issues for this organization** should be disabled.\n\nThese settings probably won't have much impact:\n\n* **Allow forking of private repositories** should be disabled just to keep\n  access tidy.\n* **Allow users with read access to create discussions** is confusingly under\n  the 'Admin repository permissions' heading but sounds rather innocuous, so it\n  can be left checked.\n\n*More settings may appear on the member privileges page at some point. Please\nupdate the above listing if/when this does occur.*\n\n[member-privileges]: https://github.com/organizations/concourse/settings/member_privileges\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconcourse%2Fgovernance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconcourse%2Fgovernance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconcourse%2Fgovernance/lists"}