Community Configuration

As handling permissions, assignments, etc. gets more and more complicated, the bigger a community gets, we decided to opt-in for a GitOps approach for community management.

We are using Peribolos which is developed and maintained by Kubernetes. They actively use it to manage their own communities, see kubernetes/org.

To reduce efforts and duplication we decided to adapt the generation apporach to our needs.

Overview

The tools/peribolosbuilder.go contains our custom generation logic for the peribolos configuration.

Within the config directory, we are storing our configurations. (this can be overwritten with a config flag (--config) when executing peribolosbuilder.go).

Configuration Structure

Each directory within the config directory represents a GitHub Organization (therefore we will refrain from it as org-folder). This directory will only be picked up when there is a org.yaml within the directory.

Within this org-folder we can have multiple teams/workgroups. Those teams are represented with their subfolder (the name of the team) containing a workgroup.yaml.

peribolosbuilder.go will fetch these configurations and generate a proper peribolos configuration based on this.

org.yaml

The org.yaml follows the default peribolos configuration format.

It will be used to:

  • define members and admins of the organization
  • define default settings for the organization such as:
    • members allowed to create repositories
    • default permissions for members
    • …
  • repositories and their configuration
  • global teams

special teams

There are 3 special teams within the org.yaml.

Those are

<workgroup>/workgroup.yaml

Each workgroup represents an organizational unit, which needs to work on the same repositories.

A workgroup consists of following roles:

  • approvers (triage permission)
  • maintainers (maintain permission)
  • admins (admin permission)

Based on the definition above a workgroup.yaml has the following structure:

repos: # a list of repositories the team has access to
  - repo-1
  - repo-2 
  
approvers:
  - approver-1

maintainers:
  - maintainer-1

admins:
  - admins-1

Repositories are not mutually exclusive to workgroups. Hence, multiple workgroups can have access to the same repositories.

Note Use admins carefully and only when it is really needed. Admins can change secrets etc.

Based on this configuration we will generate 3 teams:

  • <workgroup>-approvers
  • <workgroup>-maintainers
  • <workgroup>-admins

Furthermore, we will assign those 3 teams also permissions for the defined repositories.

Example

Let’s say we have a workgroup.yaml within org-folder/workgroup.

The content is:

repos:
  - repo-1
  
approvers:
  - approver-1

maintainers:
  - maintainer-1

admins:
  - admins-1

Following Teams will be generated, with the respective permissions for the repository repo-1:

  • workgroup-approvers: triage
  • workgroup-maintainers: maintain
  • workgroup-admins: admin

How to

… add a member to the organization?

Add them within the org.yaml of the GitHub Organization to the list of members.

members:
  - <githubHandle>

… generate a new workgroup?

Generate a directory within the org-folder of the GitHub Organization with the team name. Add a workgroup.yaml defining the repos, approvers, maintainers, and admins.

repos:
  - repo-1
  
approvers:
  - approver-1

maintainers:
  - maintainer-1

admins:
  - admins-1

… set a member as emiritus?

Warning First discuss this with the community and the member you want to set to emiritus state.

Remove the member from all workgroup.yaml files, and other teams within the org.yaml.

If the user used to be an Admin of the organization moves them from admins to members in the org.yaml.

Add the user to the emeritus-team definition within org.yaml` of the desired GitHub Organization.

… create a new repository?

Within the org.yaml of the designated organization, add an entry in the repos section. As an example, we want to add a new repository called peribolos-test, we will add the following:

repos:
  # ...
  peribolos-test:
    description: "my peribolos test"
  # ...

Execution locally

  1. Generate a config

    cd tools && go run peribolosbuilder.go -config=../config > ../peribolos.yml && cd ..

  2. Generate a Token with repo, user and org:admin permissions and save it in a file called github-token

  3. Run following command to test our configuration

    docker run --rm -v $(pwd)/github-token:/github-token -v $(pwd)/peribolos.yml:/peribolos.yml ghcr.io/dynatrace-innovationlab/peribolos:latest --github-token-path github-token --fix-org --fix-org-members --fix-repos --fix-teams --fix-team-members --fix-team-repos --github-allowed-burst=300 --github-hourly-tokens=1000 --config-path peribolos.yml

    You can even skip some of the commands to test certain functionalities, eg. only run --fix-org --fix-org-member.

Warning Per default peribolos runs without applying changes. If you provide the flag --confirm it will apply the changes.