You cannot use or reference an orb within another orb in CircleCI. Orbs are a closed scope, meaning you cannot reference an inline orb from within another inline orb, nor can you nest orbs inside each other. Each orb is self-contained and cannot import or use other orbs directly within its own definition. This limitation applies to both inline orbs and published orbs across all CircleCI configurations.

CircleCI orbs operate within a closed scope architecture that prevents orb nesting or cross-referencing. This design ensures that each orb remains independent and self-contained, avoiding potential conflicts or circular dependencies that could arise from orb composition.

No Direct Orb Imports: You cannot use orbs: declarations within an orb definition to import other orbs. Each orb must contain all the functionality it needs within its own scope.

No Inline Orb References: Inline orbs cannot reference other inline orbs, maintaining the same isolation principles as published orbs.

Self-Contained Functionality: All commands, jobs, and executors used by an orb must be defined within that orb's own configuration.

If you need to use functionality from multiple orbs, you should import and use them separately in your project's configuration file, not within the orb definitions themselves:

When you need to share logic between orbs, you have several options:

Duplicate Configuration: Copy the common configuration elements into each orb that needs them. While this creates some duplication, it maintains the self-contained nature of each orb.

Factor Out Common Logic: Create reusable commands or jobs that can be included in each orb as needed. This involves copying the common elements into each orb's definition rather than referencing them externally.

Modular Orb Design: Design your orbs to be more granular and focused on specific functionality, allowing consumers to combine multiple specialized orbs rather than creating complex, multi-purpose orbs.

This limitation encourages a modular approach to orb design where each orb focuses on a specific domain or functionality. Rather than creating large, monolithic orbs that try to encompass multiple concerns, the ecosystem benefits from smaller, focused orbs that can be composed at the project level.

Since orbs cannot depend on other orbs, you must carefully consider what functionality to include within each orb. This often means including all necessary commands, jobs, and executors within the orb itself, even if similar functionality exists in other orbs.

Consistent Behavior: This limitation applies uniformly across all orb types, ensuring consistent behavior whether you're working with inline orbs or published orbs from the registry.

Ecosystem Benefits: While this constraint may seem limiting, it promotes a cleaner orb ecosystem where dependencies are explicit and managed at the project level rather than hidden within orb definitions.

Composition at Project Level: The proper way to combine orb functionality is at the project configuration level, where you can explicitly declare and orchestrate multiple orbs to work together.

Future Considerations: This architectural decision helps maintain the stability and predictability of the CircleCI orb ecosystem by avoiding complex dependency chains and potential conflicts.