Packages concepts

Here are some concepts and terms to know when managing, publishing, or consuming packages in CodeCatalyst.

Packages

A package is a bundle that includes both software and the metadata that is required to install the software and resolve any dependencies. CodeCatalyst supports the npm package format.

A package consists of:

Package namespaces

Some package formats support hierarchical package names to organize packages into logical groups and to help avoid name collisions. Packages that have the same name can be stored in different namespaces. For example, npm supports scopes, and the npm package @types/node has a scope of @types and a name of node. There are many other package names in the @types scope. In CodeCatalyst, the scope (“types”) is referred to as the package namespace, and the name (“node”) is referred to as the package name. For Maven packages, the package namespace corresponds to the Maven groupID. The Maven package org.apache.logging.log4j:log4j has a groupID (package namespace) of org.apache.logging.log4j and the artifactID (package name) log4j. Some package formats such as Python don't support hierarchical names with a concept similar to npm scope or Maven groupID. If you don't have a way to group package names, it can be more difficult to avoid name collisions.

Package versions

A package version identifies the specific version of a package, such as @types/node@12.6.9. The version number format and semantics vary for different package formats. For example, npm package versions must conform to the Semantic Versioning specification. In CodeCatalyst, a package version consists of the version identifier, package-version-level metadata, and a set of assets.

Assets

An asset is an individual file stored in CodeCatalyst that is associated with a package version, such as an npm .tgz file or a Maven POM or JAR file.

Package repositories

A CodeCatalyst package repository contains a set of packages, which contain package versions, each of which maps to a set of assets. Package repositories are polyglot, meaning a single repository can contain packages of any supported type. Each package repository exposes endpoints for fetching and publishing packages using tools like the NuGet CLIs (nuget, dotnet), the npm CLI, the Maven CLI (mvn), and the Python CLIs (pip and twine). For information about packages quotas in CodeCatalyst, including how many package repositories can be created in each space, see Quotas for packages.

You can link a package repository to another by setting it as an upstream. When a repository is set as an upstream, you can use any package from the upstream as well as any additional upstream repositories in the chain. For more information, see Upstream repositories.

Gateway repositories are a special type of package repository that pulls and stores packages from official external package authorities. For more information, see Gateway repositories.

Upstream repositories

You can use CodeCatalyst to create an upstream relationship between two package repositories. A package repository is an upstream of another when the package versions it contains can be accessed from the package repository endpoint of the downstream repository. With an upstream relationship, the contents of the two package repositories are effectively merged from the point of view of a client.

For example, if a package manager requests a package version that does not exist in a repository, CodeCatalyst will then search configured upstream repositories for the package version. Upstream repositories are searched in the order they are configured, and once a package is found, CodeCatalyst will stop searching.

Gateway repositories

A gateway repository is a special type of package repository that is connected to a supported external, official package authority. When you add a gateway repository as an upstream repository, you can consume packages from the corresponding official package authority. Your downstream repository does not communicate to the public repository, instead, everything is intermediated by the gateway repository. Packages consumed in this manner are stored in both the gateway repository and the downstream repository that received the original request.

Gateway repositories are predefined, but they must be created in each project to be used. The following list contains every gateway repository that can be created in CodeCatalyst and the package authority they are connected to.