governance

This repository is the source of truth for the Tech Committee's governance model. It declaratively manages teams, repositories, and membership using OpenTofu and Atlantis.

Joining a team

1. Link all available accounts in Keycloak.
2. Add your git.cmu.dev username to the members array in the desired team .toml file under data/.
3. Open a PR using a conventional PR title.

Note that only team leads are allowed to modify other people's memberships.

Creating a team

Teams are groups of leads, members, repositories, and channels. They can nest sub-projects recursively, each with the same shape. Copy an existing file in data/teams/ for a working starting point.

Reference the team schema for an authoritative list of fields and their constraints.

Features

Each repository opts into capabilities through its features table. Presence enables a feature, an empty table enables it with defaults, and features with settings take them as keys:

[[team.repos]]
name = "collie"
features = { kennel = {}, sentry = {} }

[team.repos.features.ai_gateway]
prod_monthly_budget = 20.0

• kennel adds a Forgejo webhook that connects the repository to kennel for builds and deployments
• sentry creates a Sentry project and writes its DSN to Vault
• posthog creates a PostHog project and writes its key and host to Vault
• cdn creates a public-read Garage bucket for the repository and writes its S3 credentials and public URL to Vault
• oidc_client provisions prod and staging Keycloak OIDC clients with a fixed redirect URI and writes their credentials to Vault per profile; set admin = true to also provision a service-account client with user-management roles and write its credentials to Vault, and list groups to create extra Keycloak groups
• ai_gateway provisions LiteLLM API keys with monthly budgets, a prod key and a lower-budget key shared by staging, preview, and dev, and writes the key and gateway URL to Vault per profile
• docs registers the repository's docs/ directory with the documentation hub

How a project declares and consumes what these provision lives in the kennel docs: Deploying a Project and Secrets.

Keycloak groups

The oidc_client feature can declare extra Keycloak groups. Governance creates them under the project group and projects are left to manage the members.

[[team.projects.repos]]
name = "quest"

[team.projects.repos.features.oidc_client]
groups = ["staff"]

That creates /projects/quest/staff as an empty group to be filled in the Keycloak admin console afterwards.

These groups appear in the OIDC groups claim like any other, so the app can authorize against <PROJECT_GROUP>/staff. They carry no OpenBao access.

Description

The following is a list of platforms Governance manages:

1. Keycloak
   • Members are added to their team's Keycloak groups, which gives them permission to access environment variables and other project-specific resources
   • Team leads are further added to the team's admins subgroup, which gives additional access
   • For projects with it enabled, OIDC clients are provisioned
   • Groups a repository lists under oidc_client are created with their members left to be managed in Keycloak
2. OpenBao
   • Keycloak groups are given the appropriate access to secret paths on OpenBao
3. git.cmu.dev
   • Members are added to their Forgejo teams, which gives them appropriate access to the team's repositories
   • Forgejo repositories are set up to automatically sync to GitHub for visibility
4. Google
   • Members are automatically added to ScottyLabs' and Tech's mailing lists (Google Groups)
5. Sentry
   • Projects are provisioned under Sentry
6. PostHog
   • Projects are provisioned under PostHog for product analytics
   • Leads of teams with a PostHog project are invited as organization members, and devops as owners
7. LiteLLM
   • Repositories with the AI gateway enabled receive budgeted API keys under their team, written to OpenBao per profile
8. Kennel
   • Repositories automatically receive a deploy webhook that authorizes them to be deployed by kennel
9. Website
   • Groups with a public_url are published to the scottylabs.org project catalog
10. Discord and Slack
    • Members are added to the appropriate channels on both platforms
    • On Discord, members are assigned the Tech role and their team's roles, and team leads additionally receive the Tech Lead role
    • Bidirectional sync is established between registered Discord and Slack channels via Matrix
11. Vaultwarden
    • Members are given the appropriate access to account credentials on Vaultwarden

Here, "appropriate access" serves to delineate between member permissions and team lead permissions.