What is a Hybrid Repository Structure?

We often advise our customers to consider a “Hybrid” repository structure, which incorporates both the development environment (dev, staging, prod) and the specific team/application/service for artifact repositories in Cloudsmith. This is essentially just adding another layer to the team/application/service specific repository structure that provides better visibility and traceability of different environments.

It might help to visualize the hybrid approach (we’ll discuss what we mean by “automated promotion” below).

Why Choose a Hybrid Repository Structure?

You might consider a hybrid repository structure if you find that a purely environment-based or purely team-based model leaves gaps in your workflow. For example, if your artifact repositories are currently team-based (set up solely by teams/services/applications), it can be difficult to put the right artifact promotion workflows in place without leveraging very strict artifact tagging practices. It also makes it harder to view artifacts across your various development stages. On the other hand, if you use an environment-based model group by development environment) without clear distinctions between teams/services/applications, you might run into visibility and traceability issues across artifacts.

We often see Cloudsmith customers that have outgrown single-model repository setups and are beginning to feel growing pains. As your organization grows, so does the demand for more efficient software development practices. The “simpler” repository model runs the risk of ultimately creating confusion, duplication, and lack of accountability. The hybrid approach contains that complexity in a clear and concise way that aligns with your development environments and organizational structure.

When To Choose a Hybrid Repository Structure?

Different compliance requirements across applications and environments is often a trigger for moving to a hybrid repository structure. For example, if your production environment for your government-facing application needs stricter security controls than your development environment for an internal application, a hybrid approach lets you apply different vulnerability policies to each.

Another reason to choose a hybrid structure is when you start getting into different product lines, diverse tech stacks, or growing sets of microservices. If you need to ensure that each product or service can move through specific stages of development independently, the hybrid approach makes that possible without sacrificing consistency.

It also rewards organizations that value observability. For instance, there may be times where you may need to investigate rogue image downloads from specific client requests within your staging environment that are causing a spike in package delivery demand. Or consider what happens when a pipeline has ingested a malicious package and you need to trace back to the originating repository. If the hybrid approach is adopted correctly, both of these situations can be addressed a lot more easily and quickly by security and observability teams.

At Cloudsmith, we partner closely with SRE’s and infosec teams early in the onboarding process to ensure our customers are well equipped to handle these situations.

Benefits of the Hybrid Approach

• One of the more popular topics we discuss during customer onboardings is the practice of artifact promotion across repositories. Package promotion workflows can be the place where artifact management breaks down in less structured setups.
  In the hybrid model, environment based repositories act as quality gates that artifacts must pass through before reaching production. This ensures that only vetted, tested, and approved artifacts move forward, reducing the risk of instability, untested code, or vulnerable code being deployed into customer-facing applications. Development teams can still own and manage their artifacts independently, while the environment boundaries guarantee a consistent, auditable path throughout the artifact lifecycle.
• The other significant benefits of the hybrid approach are visibility and governance. With a purely environment-based structure, it can be difficult to quickly identify who “owns” a package or service, while a purely service-based approach risks muddying the waters when promoting artifacts across environments.
  The hybrid approach solves this tension but allows teams to retain clear ownership of their artifacts, while environment-based repositories enforce quality “gates” as well as access controls as packages move from development to staging, to production.
• A hybrid repository structure strikes the balance between order and flexibility. By combining environment-based repositories (development, staging, and production) with service, application, or team-specific segmentation, organizations gain more control over how software flows through their pipelines without losing sight of ownership or accountability.
  This approach creates clear boundaries between environments while still aligning repositories with the way development teams actually build and ship software.

How to Implement the Ideal Hybrid Repository Structure?

There isn’t a “one-size-fits-all” approach to implement a hybrid repository structure, but there are a few patterns that work especially well depending on how your organization is structured. One common approach is to segment by team and environment. For example, you might have repositories like frontend-dev, frontend-staging, and frontend-prod, alongside backend-dev, backend-staging, and backend-prod. This approach works well when you have dedicated frontend and backend teams who need clear ownership of their artifacts, while environment-based repositories provide the quality gates required to promote code safely through your organization’s environments.

Another variation is to organize by product/service and environment, such as payments-dev, payments-staging, and payments-prod for services. This model is particularly effective for organizations running microservices or multiple customer-facing products. Each service has a self-contained promotion pipeline making it easier to test, release and troubleshoot independently without impacting other teams. Larger organizations sometimes prefer a department or function-based hybrid model, where repositories are grouped for example by mobile-dev, mobile-staging, mobile-prod for a mobile app focused engineering team, while a data focused team might have their own set of similar repositories. Again, this keeps things scalable and avoids proliferation of repositories, while still ensuring environment-based control.

Finally, a useful approach includes a shared dependency repository alongside service and environment repositories. For example, you might have a shared-libs repository where internal SDKs, libraries, and external dependencies might live to be used across multiple services or applications. The Cloudsmith customer success team often recommends enterprise customers adopt this approach for both deduplication of dependencies as well as ensuring there is a dedicated “ingress” repository that acts as a security gate for proxied dependencies. This avoids having multiple “development” repositories having multiple upstream configurations and helps greatly with auditability.

Companies with just a few major products often do best with a product + environment structure, while those running many microservices benefit from a service + environment structure. Smaller, more agile teams might lean towards a team + environment approach to meet their specific needs. In most enterprise environments, it’s actually common to mix multiple hybrid patterns within a single artifact registry. Your teams might use all 3 of the above approaches depending on specific workflow requirements. We call this “multi-pattern hybrid repository structure”.

For each of the above hybrid structures, our customers have the ability to automate the creation of these repositories on behalf of their development teams using our REST API and Terraform provider, with some customers even creating golden paths or secure self-service workflows to enable development speed and freedom. Overall, the key to getting the hybrid approach just right for your organization is to align your repositories with how your development teams are organized as well as how your CI/CD pipelines actually operate.

Cloudsmith’s Support for Hybrid Repository Structures

Cloudsmith is the modern way to store and distribute your software at scale, securely. With Cloudsmith’s multi-format support and build-in scale, we are able to meet the needs of the largest enterprises building and distributing software today. Gone are the days of language formats bound to repositories and limits on how many repositories you can create.

With Cloudsmith, your developers are able to spin up new globally distributed repositories with just a few clicks or commands to meet their needs. All of this comes out of the box with Cloudsmith. The Cloudsmith Customer Success team is here to help you navigate repository configurations, especially the hybrid approach given the amount of customers we have benefitting from this approach.

If you haven’t already, check out our previous post, “Why Repository Structure Matters”, where we break down the foundational principles behind effective repository organization and how the right structure can shape your software delivery success.