In one line
Governance is deciding who can do what.
Start with your orgs. Then shape them with teams, policies and rulesets.
Rules flow downward, to repos and to Copilot.
Three org models ๐ Docs ๐ข Ricoh case
First decision: how many orgs? Each model changes what everyone can see by default.
Granting access ๐ Docs
Now let people in: IdP โ teams โ repos. Never individuals.
flowchart LR
IDP["๐ชช IdP (Okta)<br/>single source"]
ENT["๐๏ธ Enterprise Team ๐<br/>Admin ยท all orgs"]
ORG["๐ข Org Team ๐<br/>this org ยท from org chart"]
REPO["๐ฆ Repository"]
IDP -->|SCIM| ENT
IDP -->|SCIM| ORG
ORG -->|Write etc.| REPO
ENT -->|Admin| REPO
classDef idp fill:#1a0a2e,stroke:#ffb000,color:#ffb000,stroke-width:2px
classDef ent fill:#2a0a0a,stroke:#ff5555,color:#ff5555,stroke-width:2px
classDef org fill:#0a0e27,stroke:#00f0ff,color:#00f0ff,stroke-width:2px
classDef repo fill:#0a1a14,stroke:#9bbc0f,color:#9bbc0f,stroke-width:2px
class IDP idp
class ENT ent
class ORG org
class REPO repo
click ENT href "https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams" "Enterprise teams docs" _blank
click ORG href "https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams" "Organization teams docs" _blankPolicies
People are in. Policies decide what they may do โ set at org and enterprise, never at the repo.
- ๐๏ธ Enterprise โ SSO / SCIM, allowed features, base policy for every org
- ๐ข Org โ member privileges, repo creation, 2FA, Copilot and Actions access
- ๐ฆ Repo โ holds no policy, only inherits. The one thing a repo adds is a ruleset.
- ๐ Rules flow down. An org can tighten enterprise rules, never loosen them.
๐ฏ Set guardrails top-down. Never repo by repo. Org policies โ ยท Enterprise policies โ
Admin roles ๐ Docs
Policies are set. Now, who may change them? That is not a repo role.
- ๐๏ธ Enterprise owner โ every setting and policy, yet no org settings or content by default
- ๐ข Org owner โ full control of one org. Keep it small, never below two.
- ๐ก๏ธ Security manager โ read on every repo plus alert management. Security teams need no Owner
- ๐งฉ Custom org roles โ bundle only what is needed, e.g. โview the audit logโ (GHEC)
๐ฏ Owner is a key, not a job title. Look for a smaller role first. Org roles โ ยท Custom org roles โ
Repository roles
Now inside the repo: who does what. Roles are cumulative.
| Role | Adds to the role below |
|---|---|
| ๐ Read | View, clone, open issues |
| ๐บ Triage | Manage issues and PRs โ label, assign, close |
| โ๏ธ Write | Push and merge |
| ๐ ๏ธ Maintain | Non-destructive repo settings |
| ๐ Admin | Full control โ access, visibility, deletion |
๐งฉ If none fit, build a custom repository role at org level from any base role. Custom roles โ
Rulesets ๐ Docs
Policies say what is allowed, roles say who acts. Rulesets say what the code must pass.
- ๐ก๏ธ Branch protectionโs successor โ reviews, checks, signing, force-push bans, in one object
- ๐๏ธ Defined at ENT / ORG / REPO โ set it high and every repo below inherits it
- ๐ They stack โ when several apply, the strictest wins. No loosening below
- ๐งช Evaluate mode โ measure impact without enforcing. Start here on existing repos
๐ฏ Donโt grant bypass. A ruleset with bypass is a request, not a rule. Org rulesets โ
12 anti-patterns
That is the structure. Here is what breaks it. 01, 02 and 11 are the hard ones to undo.
The 18 guardrails ๐ Docs
Now the values to set, and who sets them. Short on time? 03, 15, 18.
Copilot managed settings (NEW)
Same idea for Copilot clients: copilot/managed-settings.json overrides local settings. Order: MDM โ server-managed โ file โ user. All keys โ
.github-private & source org
They live in one repo you own, set in Enterprise โ AI controls โ Agents.
.github-private/
โโโ agents/ # published enterprise-wide
โโโ .github/agents/ # staging, test before publishing
โโโ copilot/
โโโ managed-settings.json # the baseline
โโโ team-mappings.json # file โ enterprise team
โโโ teams/*.json # per-team override- ๐ข You pick the org. The repo name and
copilot/paths are fixed. - ๐ Applies to everyone on the plan, repo access or not. Keep it internal and guard
copilot/**with CODEOWNERS.
โ Where it fits
Five layers, one rule: set them from the top.
| Layer | Scope | Examples |
|---|---|---|
| ๐ข Policies | org โ enterprise | 2FA, visibility, feature access |
| ๐ Admin roles | org โ enterprise | Owner, Security manager, custom |
| ๐ค Permission roles | Repository | Read / Write / Admin |
| ๐ก๏ธ Rulesets | Branches and tags | Required reviews, required checks, signing |
| ๐ค Managed settings | Copilot clients | Default model, bypass lock, plugins |
๐ฏ Top-down wins. Per-repo does not scale.