Repositories
Connected repositories
Early Access
Connected Repositories are in early access and are currently supported for Maven, Docker, Python, NPM, Go, Cargo (Rust), NuGet, Helm, Conan, Conda, Generic, and Nix. Please contact us if you are interested in trying them.
Connected Repositories allow you to natively link multiple repositories together within a single repository, making packages from all connected repositories available through the repository that the connections are created on.
How it works
When a repository has connections, package resolution happens within the context of a single request. There is no redirection between repositories, and packages pushed to any connected repository are immediately visible to consumers of the primary repository.
- Packages are available instantaneously from all connected repositories as soon as they are pushed or updated - no indexing required. This happens because cache invalidation is triggered within the primary repository as soon as a package is pushed or updated in any connected repository.
- Package resolution happens inside a single request with no redirection, significantly improving performance. Native package management tools receive a flattened blended view of packages from all configured repositories.
Priority
Each connected repository is assigned an integer priority, which determines the order in which repositories are evaluated during package resolution. This is important when the requested package exists in multiple connected repositories.
Resolution order follows 1..n, where 1 is the highest priority. When multiple connected repositories share the same priority value, the configuration creation date is used as a tiebreaker.
Upstream inheritance
Upstreams configured on connected repositories are automatically available through the primary repository. For example, if Repository A has a connection to Repository B, and Repository B has upstreams pointing to PyPI and PyTorch, consumers of Repository A can resolve packages from both upstreams.
Packages fetched from inherited upstreams are cached in the repository where the upstream is configured (i.e., Repository B in this example).
When blending upstreams across connected repositories, relative priorities are dynamically calculated based on the priority of each connection. For example, if Repository A has two connections each with priority 1 on their respective repositories, the upstream from the higher-priority connection will be assigned relative priority 1, and the upstream from the lower-priority connection will be assigned relative priority 2.
Packages are always resolved in the following order:
- Packages within the primary repository.
- Packages within any of the connected repositories, evaluated in priority order.
- Upstream packages, evaluated in relative priority order (beginning with upstreams defined on the primary repository).
Example repository configuration
Requirements
To create a connected repository configuration, you must have:
- Administrator privileges on the repository you are creating the connection on (the "primary" repository).
- At least Read privileges on the repository you are connecting to.
This mirrors the permission model used for upstreams.
Supported formats
| Format | Connected Repositories Support |
|---|---|
| Maven | ✅ |
| Docker | ✅ |
| Python | ✅ |
| NPM | ✅ |
| Go | ✅ |
| NuGet | ✅ |
| Cargo (Rust) | ✅ |
| Helm | ✅ |
| Conan | ✅ |
| Conda | ✅ |
| Generic | ✅ |
| Nix | ✅ |
Support for additional formats is planned.
Configuring connected repositories
Connected repositories can be configured via the Cloudsmith web app or API.
Using the Cloudsmith web app
To configure a connected repository in the web app, go to the Sources tab of the repository you want to configure as the primary repository. In the Connected repositories section, click Connect repository.
Select the target repository and assign it a priority to create the connection.
Using the API
Connected Repositories API endpoints are available to manage connections programmatically. Connections can also be configured using the Cloudsmith Terraform Provider.
In summary, the following operations are available:
| Operation | Description |
|---|---|
| Create | Create a new connected repository configuration |
| List | List all connected repository configurations for a repository |
| Update | Update the priority or target of an existing configuration |
| Delete | Remove a connected repository configuration |
Viewing packages from connected repositories
The package list displays a Source column indicating whether each package belongs to the repository itself or originates from a connected repository.
If a repository has one or more connected repositories configured, a Connected packages toggle is displayed above the package list. Enabling this toggle includes packages from all connected repositories in the results. Repositories without any connected repositories configured do not display this toggle.
The package list can also be filtered by source. Use the source:connected_repository filter to limit results to packages originating from connected repositories.
Packages from connected repositories are visible in the list and can be inspected, but cannot be quarantined or otherwise acted upon from the primary repository, since these actions must be performed on the repository the package belongs to.
Behavior and considerations
Access control
Connecting Repository A to Repository B gives consumers of Repository A implicit access to view and download packages within Repository B via native tooling.
Audit logs
Audit log entries are created when connected repository configurations are created, updated, or deleted.
Download attribution
When a package download occurs through the primary repository for a package that belongs to a connected repository, the client log entry is produced for the primary repository. The individual package download count is incremented on the package in the repository where it resides.
Client log entries for these downloads display a connected repository icon in the event list. Expanding an entry surfaces a Connected repository section listing the primary repository the download was served through and the connected repository the package belongs to.
Note
A client log entry is only produced for the primary repository. No corresponding entry is produced for the connected repository the package belongs to.
For example, if Repository A has a connection to Repository B, downloads of packages belonging to Repository B that occur through Repository A are logged against Repository A only.
Note
Client logs cannot be filtered by connected repository. To determine which downloads originated from a specific connected repository, entries must be reviewed individually.
Package signatures
Connected repositories do not cache packages. Package signatures are sourced from the repository where the package belongs and are signed using that repository's key. Policies continue to apply to packages within the repository they belong to.
Nested connections
We do not support the ability to nest connected repositories (i.e. Repository A has a connection to Repository B, which has a connection to Repository C). All connections must be directly configured on the primary repository. This limitation is purposeful as we believe it is a more intuitive model and nested configurations can almost always be flattened into a non-nested configuration with the same effective resolution order.
Current limitations
The following is a non-exhaustive list of known limitations during Early Access:
- OSS repositories: Connected repository configurations cannot be created on OSS repositories, or targeting OSS repositories.
- Cross-workspace: Connected repositories can only be configured between repositories within the same workspace.
- Repository restrictions: Repository level restrictions such as Geo/IP Rules and EULA enforcement must be defined on the source repository. These restrictions are not inherited from connected repositories.
