Almost nobody chooses their organisation structure. It accumulates.
Someone creates an organisation for a project. A team that joined through an acquisition keeps theirs. A department wants separate billing. Five years later there are twenty-three organisations, nobody can say what the boundary between them means, and every governance change has to be applied twenty-three times.
The short answer
Section titled “The short answer”The enterprise contains organisations; organisations own repositories. GitHub’s documentation is explicit that “repositories are owned by organizations and are not directly accessible under the enterprise account.”
An organisation boundary is a permission boundary, a settings boundary and a teams boundary. It is not a billing boundary in the enterprise model, and it is not a security boundary in the sense people frequently assume.
Fewer, larger organisations are usually better, because most of the reasons to split turn out to be solvable within one organisation, and every split multiplies the governance work.
The exceptions are real — legal separation, genuinely distinct access populations, acquisitions — and they are fewer than the number of organisations most enterprises have.
What an organisation boundary actually controls
Section titled “What an organisation boundary actually controls”Be precise about this, because most structure decisions are made on assumptions that are wrong.
Membership. Organisation members are a defined set. Somebody in organisation A is not in organisation B unless separately added.
Teams. Teams belong to an organisation. A team cannot span organisations, which means a group of people working across two organisations must be maintained twice.
Base permissions. The default access every member has to every repository in that organisation. This is set per organisation.
Organisation settings. Actions permissions, default branch name, member privileges, security settings — each configured per organisation, unless the enterprise mandates a value.
Organisation-level rulesets and custom properties. Both are defined per organisation.
Repository naming. Repository names are unique within an organisation. Two organisations can each have a platform repository.
What it does not control matters just as much:
- It is not a hard security boundary for internal repositories. GitHub documents that “Organization members have read permissions to all internal repositories in an enterprise, including those in organizations they are not a member of.” Splitting into organisations does not hide internal repositories from other organisations’ members.
- It is not a billing boundary under an enterprise account, where billing is at the enterprise level with cost centers for attribution.
- It does not isolate identity. Enterprise SSO and SCIM operate at the enterprise level.
The case for few organisations
Section titled “The case for few organisations”Every governance artifact is per organisation. Rulesets, custom properties, teams, webhooks, apps, Actions settings. Twenty organisations means twenty copies of each, drifting apart from the day they are created.
Cross-team work becomes friction. A person contributing to two organisations needs membership in both, appears in two team structures, and shows up twice in every access review.
Discovery suffers. Code search, project boards and the repository list are all easier to navigate within one organisation.
Automation multiplies. Every script, every app installation, every integration is configured per organisation.
Enterprise rulesets mitigate this — they can target organisations — but they do not eliminate it, because plenty of configuration has no enterprise-level equivalent.
The practical test: if you cannot state, in one sentence, what makes a repository belong to organisation A rather than organisation B, you have one organisation with an arbitrary partition.
The case for several
Section titled “The case for several”The reasons that genuinely justify a split.
Legal or regulatory separation. A subsidiary that must be able to demonstrate separate control, or a joint venture where the other party’s people need access to some things and not others.
Genuinely distinct populations. A contractor organisation whose members must not become members of the main one. Membership is the boundary that actually works.
Acquisitions, temporarily. An acquired company arrives with an organisation. Merging takes time, and running it separately during integration is reasonable — provided somebody owns the plan to merge it.
Public presence. Some enterprises separate their open-source organisation from internal work, because the settings appropriate to public repositories differ substantially and the audience is different.
Radically different operating models. A research group whose repositories are experiments with a lifespan of weeks, alongside a production estate with strict controls. Possible in one organisation with custom properties and targeted rulesets — but if the difference is total, separation is defensible.
What is not a good reason: team structure, product lines, geography, or “it feels tidier”. Those are metadata, and custom properties express them better than organisation boundaries.
Modelling structure with metadata instead
Section titled “Modelling structure with metadata instead”The insight that resolves most structure debates.
Almost every reason to split is really a desire to treat some repositories differently from others. Different rules, different reviewers, different retention, different visibility defaults.
That is a targeting problem, not a containment problem. GitHub’s rulesets can target repositories by custom property — a filter expression on properties such as visibility, team ownership, or a tier you define.
So the structure becomes: one organisation (or few), with custom properties expressing everything you would otherwise have encoded in the organisation boundary, and rulesets targeted by those properties.
The advantages are substantial. A repository can change tier without moving. A repository can be in two categories at once. A new category needs no new organisation. And the governance is expressed as data rather than as folder structure.
The limit is membership. Properties cannot make somebody a member of a subset of an organisation. When the requirement is genuinely about who can be in the room, an organisation boundary is the right tool.
Teams, and why they are the real structure
Section titled “Teams, and why they are the real structure”Organisations get the attention; teams do the work. A structure discussion that ignores teams is missing where most of the pain is.
Teams grant access. A repository’s permissions are almost always granted to teams rather than individuals, because individual grants are unmaintainable at scale.
Teams nest. A child team inherits the parent’s repository access, which lets you model an organisation hierarchy — a platform team containing a database team and a networking team — without duplicating grants.
Teams do not cross organisations. This is the constraint that makes multi-organisation structures expensive. A group of twelve people who work across three organisations needs three team definitions, kept in sync by hand or by automation.
Team membership is where identity meets access. When teams are synchronised from an identity provider group, membership becomes a property of the corporate directory rather than something maintained in GitHub. That is the model worth aiming for; see team synchronisation and SCIM.
Design teams to match how access is actually decided. If access is granted because someone is on the payments team, there should be a payments team. If access is granted because someone is on call, there should be a team synchronised from the on-call rota. Teams that match neither become stale immediately.
The anti-pattern is a team per repository. It expresses nothing that CODEOWNERS and a repository permission do not, and it produces hundreds of teams nobody can navigate.
Nested teams plus enterprise teams — teams defined at the enterprise level, usable across organisations — reduce the multi-organisation duplication problem, though they do not remove the organisation-scoped configuration.
Base permissions: the setting that defines the estate
Section titled “Base permissions: the setting that defines the estate”Worth treating separately, because it silently determines the shape of everything else.
Base permission is the access every organisation member has to every repository in that organisation. Options are none, read, write or admin.
write is a very large grant. It means every member — including everyone SCIM has ever provisioned, including the contractor who joined last week — can push to every repository the organisation owns. Branch protection stops them merging to protected branches; nothing stops them pushing elsewhere.
read is the common choice and it is a reasonable default for an organisation practising internal transparency. It means every member can read every repository, which is a decision to make deliberately rather than inherit.
none is the strict choice, and it means all access is explicitly granted. It is correct where the repository population includes genuinely sensitive material, and it costs more administration.
The interaction with organisation structure is direct. An organisation with read base permission cannot contain a repository that only three people should see — not without an exception that is easy to forget. If you have such repositories, either they need a separate organisation, or the base permission is wrong for the organisation you have.
This is frequently the actual reason a split is being proposed, stated as something else. Ask what base permission each proposed organisation would have; if the answer is the same, the split is probably not about access.
Naming and conventions
Section titled “Naming and conventions”Whatever the structure, the naming determines whether anybody can navigate it.
Organisation names should be stable and meaningful. They appear in every URL, every clone command, every CI configuration. Renaming one is a breaking change for automation, even with redirects.
Avoid encoding transient facts. An organisation named after a product line that gets renamed, or a department that gets reorganised, is a naming problem in eighteen months.
Repository naming conventions belong at the organisation level, and can be enforced. Repository policies — documented by GitHub as currently in public preview and subject to change — include naming convention controls.
Document the convention where people will find it, which is not a wiki page nobody reads. The repository template and the creation flow are where a convention is actually communicated.
Changing the structure
Section titled “Changing the structure”Restructuring is possible and it is expensive, so do it deliberately.
-
Write down what the current boundaries mean. If you cannot, that is the finding, and it tells you the structure is arbitrary.
-
Decide the target structure and the rule. One sentence stating what determines which organisation a repository belongs to. If you cannot write it, do not restructure yet.
-
Establish metadata first. Custom properties expressing the distinctions you are about to stop encoding as boundaries. Do this before moving anything.
-
Move repositories, not everything at once. Transferring a repository between organisations preserves issues, pull requests and history, and GitHub redirects the old URL. Automation referencing the old path should still be updated.
-
Rebuild teams and permissions in the target. Teams do not move with repositories, and this is usually the largest part of the work.
-
Reconcile settings. Actions permissions, apps, webhooks, rulesets. Differences that were invisible while the organisations were separate become visible immediately.
-
Leave the empty organisation in place for a while. URL redirects and muscle memory both take time.
-
Update the policy inventory. The record of what is mandated and delegated changes with the structure.
The acquisition case
Section titled “The acquisition case”Acquisitions are the most common origin of structural disorder, and they follow a predictable pattern worth naming.
An acquired company arrives with its own organisation, its own conventions, its own identity provider, and frequently its own Git platform entirely.
Running it separately during integration is correct. Forcing a merge in week one, before anybody understands what the repositories are, produces a mess that takes longer to untangle than the delay would have cost.
The failure is not planning the merge. Six months becomes two years becomes permanent, and the organisation becomes a place where the old conventions survive because nobody owns changing them.
A workable sequence:
-
Bring the organisation into the enterprise account early, even while it stays separate. This gets audit logging, enterprise policy and identity under one roof immediately, which is the highest-value part.
-
Inventory before changing anything. What repositories exist, which are active, who owns them, what depends on them. Acquisition inventories routinely find that a third of the repositories are dead.
-
Migrate identity next. Getting the acquired population onto the enterprise identity provider is what makes access reviews and offboarding work, and it is independent of where the repositories live.
-
Archive aggressively. The cheapest repositories to migrate are the ones you do not migrate. See repository lifecycle.
-
Then decide whether to merge the organisation at all. With policy, identity and audit unified, the remaining benefit of merging is teams, discovery and settings consistency — real, but no longer urgent.
Set a date for step 5 at the start. Not because the date will be met, but because without one the question is never asked again.
If the acquisition is on a different platform, this is a migration project rather than a structure decision — see migration planning and GitHub Enterprise Importer.
Cost centers and attribution
Section titled “Cost centers and attribution”Cost centers attribute enterprise usage without requiring separate organisations.
Which removes one of the most common reasons for splitting. “Finance needs to know what each department spends” is an attribution requirement, and attribution is what cost centers are for.
Set them up before the question is asked. Retroactive attribution is much harder than ongoing attribution.
Three structures that work
Section titled “Three structures that work”Rather than a rule, three shapes that hold up, with the conditions under which each is right.
One organisation. Everything in a single organisation, differentiated by custom properties and targeted rulesets. Teams model the hierarchy; base permission is read or none.
Right when: the enterprise is a single company with a single engineering population, everybody is an employee or an equivalently-trusted contractor, and internal transparency is a value rather than a risk.
Fails when: there is a population that must not have blanket read access, or a legal requirement for separation.
A small number of organisations by trust boundary. Typically: the main engineering organisation, one for open-source work, and one for external collaborators. Perhaps a fourth for anything with a genuinely restricted population.
Right when: there are distinct populations with distinct access, and the boundaries can be stated as “who is allowed to be a member”.
Fails when: the boundaries start being used for categorisation instead, at which point they multiply.
One organisation per legal entity. For enterprises that are genuinely several companies — a group with subsidiaries, or a business with regulated units requiring demonstrable separation.
Right when: an auditor would ask about separation, or a data-sharing agreement constrains it.
Fails when: the entities share engineering staff who then need membership everywhere.
What all three have in common: the rule for which organisation a repository belongs to can be stated in one sentence, and the sentence is about people, not about categories. Whenever the sentence is about categories, custom properties are the better mechanism.
Signals your structure is wrong
Section titled “Signals your structure is wrong”Rather than auditing everything, look for these.
Governance changes take weeks because each one has to be applied in many places, by hand, and verified in each.
Nobody can list the organisations from memory — and the list, when produced, contains ones people are surprised by.
Repositories are in the “wrong” organisation and everyone knows it, but moving them is too disruptive to bother.
The same team exists three times with slightly different membership in each organisation.
Access reviews take a person-week because there is no single place to see who has what.
New repositories go wherever the creator has permission, rather than where they belong.
An organisation has one repository, or none. Usually the residue of a project or an acquisition, and usually a candidate for consolidation.
Settings differ between organisations and nobody decided that they should. Drift is the default state of duplicated configuration; if you have not actively reconciled, they have diverged.
Two or three of these are normal. All of them together means the structure is not a structure, and a deliberate consolidation will repay itself.
Common mistakes
Section titled “Common mistakes”Splitting for confidentiality and using internal repositories. Internal is readable across the enterprise regardless of organisation.
Splitting for billing. Cost centers attribute usage without the governance cost.
Splitting along team structure. Teams reorganise; repositories do not want to move every time.
Never consolidating after an acquisition. The temporary organisation becomes permanent because nobody owns the merge.
Restructuring without writing down the rule. You will end up with a different arbitrary structure.
Moving repositories without inventorying dependencies. Webhooks, apps, secrets and required checks do not all follow.
Treating organisation count as a metric to minimise for its own sake. The goal is a structure with a statable rule, not the smallest number.
Repository placement as an ongoing decision
Section titled “Repository placement as an ongoing decision”Structure is not a one-time design; it is a decision made every time somebody creates a repository, usually by somebody who has not read any of this.
Which means the creation path is where structure is actually enforced. A repository created through a self-service flow that asks the right questions ends up in the right place with the right metadata. One created through the plain interface ends up wherever the creator happened to be.
The questions worth asking at creation: which team owns this, what tier is it, what data will it hold, is it expected to be public. Those answers become custom properties, and every targeted policy afterwards depends on them being set.
Repository policies can require them. GitHub documents an option requiring explicit user-specified values for a custom property, so a repository cannot be created without one. That converts metadata from a hope into a guarantee — worth verifying against current documentation, since repository policies are documented as being in public preview.
Restricting who may create repositories is the blunter version, and it works. An enterprise policy limiting creation to organisation owners routes every new repository through a person. It also creates a queue, and queues get bypassed.
The better version is self-service with guardrails: anybody may create a repository, through a path that collects the metadata, applies the template, and sets the ownership. See repository templates and repository lifecycle governance.
Without this, structure decays continuously, and every restructuring project is followed by a slow return to disorder.
Mental model
Section titled “Mental model”An organisation is a membership boundary and a settings boundary. Everything else people use it for — categorisation, attribution, differentiated policy — is better expressed as metadata on repositories, because metadata can change without moving anything. Split when you need to control who is in the room; use custom properties for everything else.
What you learned
Section titled “What you learned”- Repositories are owned by organisations and are not directly accessible under the enterprise account
- An organisation boundary controls membership, teams, base permissions and organisation settings
- It does not hide internal repositories — enterprise members can read internal repositories in organisations they are not members of
- It is not a billing boundary; cost centers handle attribution
- Every governance artifact is per organisation, so each split multiplies the work
- Legitimate reasons to split are legal separation, distinct populations, acquisitions in progress, and public presence
- Most other reasons are targeting problems solved by custom properties and targeted rulesets
- Restructuring is possible but expensive; establish metadata before moving anything
- Transferring a repository preserves history and redirects URLs, but automation, secrets and app installations do not all follow
Exercise
Section titled “Exercise”Use an enterprise you have access to, or your own organisation.
-
List every organisation in the enterprise, with its repository count and owner.
-
For each, write one sentence stating what makes a repository belong there. Predict: how many can you write?
-
Find two organisations whose boundary you cannot justify. What would merging them cost?
-
Identify any organisation created for confidentiality that contains internal repositories. Predict: who can actually read them?
-
List the governance artifacts duplicated across organisations: rulesets, custom properties, apps, webhooks. Count the duplicates.
-
For one distinction currently encoded as an organisation boundary, design the custom property that would express it instead.
-
Pick one repository and inventory everything that references it by path: webhooks, secrets, workflows in other repositories, external systems. Predict: how much would break on a transfer?
-
Write the one-sentence rule you would use if you were designing the structure today.