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
• 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.

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
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.