Organizations model real-world business structure (companies, business units, departments, and working groups) within CloudBees Unify. This page explains the organizational hierarchy model, what organizations are and aren’t meant to represent, inheritance rules, and how organizations relate to components and access control.
Tenants and organizations
Your tenant is the top-level identity and access boundary in CloudBees Unify. When you sign up, CloudBees Unify creates a tenant and a root organization within it. The root organization is the starting point for your organizational hierarchy.
Organizations are created within the tenant to reflect your real-world structure. A root organization might represent a company, child organizations could represent business units or departments, and components represent the applications and services built by those teams.
The root organization and other organizations are the same entity with the same capabilities: the only difference is position in the hierarchy.
-
The root organization sits at the top of the hierarchy and has no parent, so it also has no sibling organizations.
-
The root organization cannot be deleted, short of deleting the entire tenant.
-
All other organizations exist somewhere beneath the root organization and can be created, renamed, or removed as your structure changes.
Every organization receives a unique organization ID that serves as its identifier across platform features and integrations. Free plan users are limited to their root organization, while paid plan users can create child organizations with complex, multi-level nesting.
Organization hierarchy
Organizations support hierarchy without restriction. Child organizations can nest within parent organizations to arbitrary depth, accommodating complex business structures.
All organizations are functionally equivalent regardless of their position in the hierarchy. Child organizations have the same capabilities as the root organization: they can contain their own components, applications, and environments, for example, and can establish their own policies and configurations.
The parent-child relationship creates natural boundaries for access control and resource management. In CloudBees Unify, users and teams are granted permissions on an organization. Those permissions can be inherited by any child or descendant organizations associated with that organization.
A typical hierarchy looks like this:
ACME (root organization)
|-- Platform
|-- Banking
`-- Insurance
|-- New Business
`-- Claims
In this example, Insurance is a child of ACME and the parent of New Business and Claims: it inherits configuration from ACME and passes that configuration down to New Business and Claims.
What an organization is not
Organizations are designed to model business structure, not applications, projects, or other technical constructs. Use components and applications to represent the software you build, and reserve organizations for the teams and business units that build it.
Modeling applications as organizations (for example, creating a separate organization for every application you own) causes problems as your usage grows:
-
It misrepresents the hierarchy. Organizations are meant to reflect business structure (enterprise, division, department), not application structure.
-
It reduces visibility and reuse across the software delivery lifecycle. An application isolated in its own organization is cut off from the shared workflows, insights, and practices you want standardized across engineering.
-
It complicates access control and auditing. Administrators end up managing identity and configuration repeatedly across many single-purpose organizations instead of from one shared parent.
-
It doesn’t scale. As the number of applications grows, the organization tree becomes bloated and stops reflecting anything meaningful about your business, making navigation and reporting harder.
Inheritance and override principles
Child organizations inherit visibility into anything declared or accessible in their parent organization unless explicitly overridden. This inheritance model reduces administrative overhead by allowing common resources, configurations, and policies to be defined once at higher levels and automatically propagated downward.
The inheritance system operates on the principle of additive access rather than restrictive inheritance. A child organization gains access to everything its parent organization can access, and can additionally define its own resources and policies.
Inheritance flows in one direction only, from parent to child; sibling organizations do not share configuration or visibility with each other. In the ACME example, Banking and Insurance inherit from ACME but have no access to each other’s configuration.
Override capabilities allow child organizations to customize inherited behavior when business requirements demand different approaches. These overrides operate selectively, meaning organizations can accept most inherited configuration while customizing specific aspects that need to differ from the parent.
The inheritance model has important security implications, as it determines how access control, policies, and resources flow through organizational hierarchies. Understanding these implications helps administrators design organizational structures that enhance security rather than inadvertently creating access vulnerabilities.
How organizations relate to applications and components
Applications and components live inside organizations, but ownership works differently for each:
-
An application belongs to exactly one organization.
-
A component belongs to the organization that contains it. An application can include a component, but including it does not transfer ownership.
-
The same component can be referenced by applications in other organizations without transferring ownership, allowing teams to reuse shared components while maintaining a single source of truth for ownership.
-
Delivery signals (deployments, builds, vulnerabilities, and similar data) roll up from components to their application, then up through the organization hierarchy.
Refer to Understanding components for more detail on how components are structured and managed.
Switching organization context
The breadcrumb navigation at the top of the CloudBees Unify interface displays your current organization and allows you to switch between organizations. Select the organization name in the breadcrumb to display other available organizations, or use the organization selector in the title bar to quickly switch context.
When you switch organization context, your permissions, visible components, and configuration options change to reflect your role within the selected organization.
Organization identity and integration
Every organization possesses a unique organization ID in the form of a universally unique identifier (UUID). These hexadecimal identifiers serve as the canonical way to reference organizations in APIs, integrations, and configuration files where human-readable names might be ambiguous or changeable.
Organization IDs appear throughout the platform in contexts where programmatic access requires unambiguous identification. They are required for API operations that target specific organizations, OIDC setup procedures that need to bind authentication to organizational contexts, and integration scenarios where external systems need to reference CloudBees Unify organizations.
Organizational context affects how platform features behave and what resources users can access. When users operate within different organizations, they may have different permissions, see different components and workflows, and access different configuration options based on their role within each organizational context.
Organization IDs also play a crucial role in multi-tenant scenarios where external systems need to maintain separate contexts for different CloudBees Unify organizations. Integration patterns often rely on organization IDs to ensure that data, configurations, and operations remain properly isolated between different business units.