The structure of your organization hierarchy decides how configuration is shared, who can access what, and how delivery data combines for reporting. A well-designed hierarchy lets you define standards once, give each part of the business the autonomy it needs, and review delivery health across the business from one place. This page gives recommendations for structuring your CloudBees Unify organizations, and assumes you’re familiar with the concepts in Understanding organizations.
| Child organizations are available on paid plans only. Free plan users are limited to the root organization. |
Design principles
The recommendations on this page follow from six principles:
-
Model business structure, not software. Organizations represent companies, business units, departments, and working groups. Applications and components represent the software they build.
-
Define shared configuration as high as possible. Most configuration defined on an organization is inherited by its descendants, so define it once at the highest organization that needs to share it.
-
Grant access as low as possible. Grant each user or team access on the lowest organization that covers their work.
-
Group what you report on together. Delivery data rolls up through the hierarchy, so a common parent gives a combined view of everything beneath it.
-
Use siblings for separation. Inheritance flows only from parent to child, so sibling organizations don’t share configuration or visibility.
-
Start shallow, but plan ahead. Each level adds administration and navigation overhead, so add a child organization only when part of your business needs something the parent can’t provide. An organization’s parent can’t be changed after it’s created, so plan the levels you expect to need before you create them.
Model business structure, not software
Organizations work best when each one maps to a part of the business that people recognize and that has its own owners.
Good candidates for an organization include:
-
A business unit, division, or subsidiary.
-
A department or engineering group with its own leadership.
-
A platform or shared services team.
-
A working group aligned to a product line or a long-running initiative.
Don’t create organizations for:
-
Individual applications, services, or repositories. Use applications and components instead.
-
Deployment stages such as development, staging, or production. Use environments instead.
-
Short-lived projects or one-off efforts.
-
Individual people.
Creating one organization per application is the most common modeling mistake. It cuts each application off from shared workflows and insights, multiplies access control and configuration work, and produces a hierarchy that stops reflecting the business as the number of applications grows. Refer to What an organization is not for more detail.
When to create a child organization
A child organization is worth its overhead when part of your business differs from its parent in at least one of these ways:
-
Ownership: It has its own administrators or leadership who manage their resources independently.
-
Configuration: It needs integrations, properties, environments, or actions that differ from the parent’s.
-
Access: Users outside it shouldn’t view or change its resources.
-
Reporting: Leadership needs a dedicated view of its delivery, security, and quality data.
-
Isolation: Legal, compliance, security, or operational requirements call for separation from the rest of the business.
If none of these apply, keep the work in the existing organization and separate it with applications and components.
Plan for inheritance
Child organizations inherit from their parent, and inheritance is additive: a child can use what its parent provides and also define its own resources. Inheritance flows in one direction only, so siblings never inherit from each other. Refer to Inheritance and override principles for how this works.
What a child inherits, and whether it can override it, varies by capability. Check Organization inheritance reference for each capability you plan to rely on, rather than assuming that everything is inherited.
|
Two capabilities break the general inheritance pattern:
Refer to Organization inheritance reference for every capability’s behavior. |
With that in mind:
-
Anchor enterprise-wide standards at the root organization. Shared source code management, CI, and project management integrations, common properties, and standard environments belong at the root, where every organization inherits them.
-
Add organization-specific configuration where it applies. For example, a business unit that uses a different issue tracker configures that integration on its own organization, so only that business unit and its descendants inherit it.
-
Override selectively. Override only the settings that must differ, and accept the rest from the parent. Overrides at many levels make the effective configuration hard to understand and audit.
-
Record why an override exists. Note the reason in the description of the configuration you create, so that future administrators don’t remove the override by mistake or copy it where it doesn’t belong.
Grant access at the lowest level that covers the work
Permissions are granted to users and teams on an organization, and apply in every descendant of that organization. That inheritance can’t be blocked for a specific child organization, so where you grant access matters as much as which role you grant. To give someone access to one department and not its siblings, grant it on that department’s organization.
-
Keep root organization access small. A grant on the root applies across the entire hierarchy, so limit it to platform administrators and leaders who need visibility across the whole business.
-
Grant access on the organization where the work happens. Members of a business unit get roles on that business unit’s organization, not on the root.
-
Grant access to teams rather than individuals. Access then follows team membership, which is easier to review and audit.
-
Choose the parent carefully when you add a child organization. A new child organization inherits its parent’s access, and its parent can’t be changed later, so create it under a parent whose access you want it to share.
Refer to Understanding role-based access control for how roles and permissions combine.
Group organizations for reporting
Delivery data, such as deployments, builds, test results, and vulnerabilities, rolls up from components to applications, to the organization that owns them, and then through each of its ancestors. A view at a parent organization includes all of its descendants, while siblings stay separate. Refer to How delivery data rolls up for details.
This makes the hierarchy a reporting structure as well as an administrative one, and each audience can use the level that matches its scope:
-
Executives and platform teams use the root organization, or a shared parent, for an enterprise-wide view of DORA metrics, flow metrics, security, and CI data.
-
Business unit leaders use their own organization for a view scoped to their departments.
-
Departments use their own organization, applications, or components for day-to-day work.
Place the departments or business units that leadership wants to compare under a common parent. If two departments that are reported on together sit in unrelated branches, the only combined view is at a higher level that also includes unrelated data.
Place shared components above the organizations that use them
A component belongs to the organization that contains it. Applications in that organization, or in any of its descendants, can reference the component without taking ownership of it, which keeps a single source of truth for code that many teams depend on. Applications in sibling or unrelated organizations can’t reference it.
Keep shared libraries, base images, and platform services in an organization above every organization that uses them, such as the root organization or the nearest parent shared by every organization that uses them. Reference them from the applications that use them, rather than duplicating them in each consuming organization.
This matters most when a platform team has its own organization. If that organization is a sibling of the organizations that consume its work, components it owns aren’t available to them. Keep the platform team’s shared components in a common ancestor, such as the root organization, and use the platform team’s own organization for work that only it uses.
Separate organizations that need isolation
Some parts of a business need strong separation, such as subsidiaries with legal or compliance boundaries. Model these as siblings directly under the root, and keep the root minimal:
-
Configure only the settings that every organization must share at the root.
-
Configure integrations, environments, and properties on each isolated organization.
-
Grant access on each isolated organization, and limit root access to the people authorized to view all of them.
Name organizations consistently
Organization names are how people find their way around the hierarchy, so they work best when they match how people already refer to that part of the business.
-
Use the business unit or department name that people already use.
-
Use one naming convention at each level of the hierarchy.
-
Leave out details that change, such as a manager’s name or a fiscal year.
Names can change, but organization IDs don’t. In APIs, OIDC configuration, and integrations, reference organizations by their organization ID, not by name.
Example: structuring six departments
A company has six departments. A central platform team manages shared integrations, and engineering leadership wants one place to view analytics for all six departments. Two structures fit, depending on how the departments relate to each other.
Flat structure
A flat structure suits departments that share most configuration and report to the same leadership.
Example Corp (root organization) |-- Platform |-- Department A |-- Department B |-- Department C |-- Department D |-- Department E `-- Department F
Shared integrations, properties, and environments are configured once at the root, and every department inherits them. Users in each department have access only to their own department’s organization. Leadership views combined analytics at the root.
Grouped structure
A grouped structure suits departments that fall into business units with their own leadership, configuration, or reporting needs.
Example Corp (root organization)
|-- Platform
|-- Consumer Products
| |-- Department A
| |-- Department B
| `-- Department C
`-- Business Products
|-- Department D
|-- Department E
`-- Department F
Enterprise standards are configured at the root. Each business unit configures what only it needs on its own organization, such as a business-unit-specific environment or issue tracker integration. Business unit leaders view analytics for their business unit, and executives view all six departments at the root.
Choosing a structure
Start with the flat structure unless a business unit clearly meets the criteria in When to create a child organization. A grouping level adds administration and navigation overhead, and it only pays for itself when the business unit has its own owners, configuration, access needs, or reporting audience.
Make this decision before you create the department organizations. An organization’s parent can’t be changed after it’s created, so adding a grouping level later means creating the business unit organizations and recreating the departments beneath them. If you already expect business units to need their own owners or reporting, start with the grouped structure.
In either structure, model each department’s applications and services as applications and components inside the department’s organization, not as additional organizations. Components that the platform team shares with every department belong to the root organization, not to Platform, because Platform is a sibling of the departments.
Checklist
Before you create or change your hierarchy, confirm that:
-
Each organization represents a part of your business, such as a business unit, department, or working group, not an application, service, environment, or project.
-
Each child organization has its own owners, configuration, access needs, reporting audience, or isolation requirement.
-
Each organization is under the parent you want it to have permanently.
-
Shared integrations, properties, and environments are defined at the highest organization that should share them.
-
Overrides are limited, and the reason for each one is recorded.
-
Root organization access is limited to users who need visibility across the whole business.
-
Departments or business units that leadership reports on together share a common parent.
-
Shared components are owned by an organization above every organization that uses them.
-
Automation and integrations reference organization IDs, not names.
-
You’ve checked the inheritance behavior of each capability you rely on.