Declarative GitHub Organisation management

[zkdev]

Context and Proposal

OCM organisation is growing, thus a scalable organisation management setup is required.

Scope

An automation MUST cover the following aspects, in a declarative way.

• Organisation members and roles
• Team lifecycle and members
• Repository contributors

Options

• otterdog
  • powerful, but configuration overhead (json templating, ...)
  • established, backed by Eclipse Foundation
• peribolos
  • used by Kubernetes
  • no recent feature development, maintenance mode? is actually actively developed, we inspect a fork at first ...
  • doc: https://docs.prow.k8s.io/docs/components/cli-tools/peribolos/
• Terraform GitHub provider
  • established and generic infra-as-code platform
  • officially supported

[zkdev]

we intend to create a little terraform (opentofu) based PoC get an understanding of the github provider usability and capabilities.

---

in our current vision we see a (set of?) github action calling whatever CLI we will use to apply declaratively configured organisation configuration. this could either be triggered manually, or via some hooks (e.g. cronjob) to implement something like a reconciliation loop.

[Skarlso]

Okay, so I investigated a POC into this and figured out that terraform will be problematic because we need to store the state and if that ever gets corrupted or destroyed or whatever, we are big trouble.

Alternatively, there is this thing called Peribolos from Kubernetes, and now uwu-tools :P This is this thing: https://github.com/kubernetes-sigs/prow/tree/main/cmd/peribolos that is used by Kubernetes ORG itself for all things that require setup. I'm looking into that.

Doc for Peribolos is correct though https://docs.prow.k8s.io/docs/components/cli-tools/peribolos/.

[Skarlso]

Peribolos example YAML:

  orgs:
    acme-co:
      billing_email: ops@acme.example
      company: ACME Co
      default_repository_permission: read
      members_can_create_repositories: false
      has_organization_projects: true
      has_repository_projects: true

      admins:
        - octocat
        - skarlso

      members:
        - alice
        - bob
        - carol

      teams:
        platform:
          description: Platform and infrastructure
          privacy: closed
          maintainers:
            - skarlso
          members:
            - alice
            - bob
          repos:
            terraform-user-management: admin
            infra-modules: write
            docs: read

          teams:
            platform-oncall:
              description: On-call subset of platform
              privacy: closed
              maintainers:
                - skarlso
              members:
                - alice

        frontend:
          description: Web and UI
          privacy: closed
          maintainers:
            - carol
          members:
            - bob
          repos:
            web-app: write
            design-system: maintain

[Skarlso]

Installation:

go install sigs.k8s.io/prow/cmd/peribolos@latest

or a container:

https://console.cloud.google.com/artifacts/docker/k8s-prow/us/gcr.io/peribolos