Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).
# Publish and share software packages in CodeCatalyst
Amazon CodeCatalyst contains a fully managed package repository service that makes it easy for your development team to securely store and share software packages used for application development. These packages are stored in package repositories, which are created and organized within projects in CodeCatalyst.
A single package repository can store packages of every supported package type. CodeCatalyst supports the following package formats:
+ npm
+ Maven
+ NuGet
+ Python
Packages in a package repository can be discovered and shared between members of the project that contains the repository.
To publish packages to, and consume packages from a repository, configure a package manager to use the repository endpoint (URL). You can then use the package manager to publish packages to the repository. You can use package managers such as Maven, Gradle, npm, yarn, nuget, dotnet, pip, and twine.
You can also configure CodeCatalyst workflows to use CodeCatalyst package repositories. For more information about using packages in workflows, see [Connecting package repositories to workflows](workflows-packages.md).
You can make packages in one package repository available to another repository in the same project by adding it as an upstream repository. All package versions available to the upstream repository are also available to the downstream repository. For more information, see [Configuring and using upstream repositories](packages-upstream-repositories.md).
You can make open-source packages available to your CodeCatalyst repository by creating a special type of repository called a **gateway**. Upstreaming to a gateway repository allows you to consume packages from popular public repositories such as npmjs.com and pypi.org, and automatically cache them in your CodeCatalyst repository. For more information, see [Connecting to public external repositories](packages-connect-external.md).
**Topics**
+ [Packages concepts](packages-concepts.md)
+ [Configuring and using package repositories](packages-repositories.md)
+ [Configuring and using upstream repositories](packages-upstream-repositories.md)
+ [Connecting to public external repositories](packages-connect-external.md)
+ [Publishing and modifying packages](working-with-packages.md)
+ [Using npm](packages-npm.md)
+ [Using Maven](packages-maven.md)
+ [Using NuGet](packages-nuget.md)
+ [Using Python](packages-python.md)
+ [Quotas for packages](packages-quotas.md)
# 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:
+ A name (for example, `webpack` is the name of a popular npm package)
+ An optional [namespace](#packages-concepts-package-namespaces) (for example, `@types` in `@types/node`)
+ A set of [versions](#packages-concepts-package-versions) (for example, `1.0.0`, `1.0.1`, `1.0.2`)
+ Package-level metadata (for example, npm dist tags)
## 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](https://semver.org/). 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](#packages-concepts-packages), which contain [package versions](#packages-concepts-package-versions), each of which maps to a set of [assets](#packages-concepts-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](packages-quotas.md).
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](#packages-concepts-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](#packages-concepts-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](#packages-concepts-upstream-repositories), 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.
+ **npm-public-registry-gateway** provides npm packages from npmjs.com.
+ **maven-central-gateway** provides Maven packages from the Maven Central repository.
+ **google-android-gateway** provides Maven packages from Google Android.
+ **commonsware-gateway** provides Maven packages from CommonsWare.
+ **gradle-plugins-gateway** provides Maven packages from Gradle Plugins.
+ **nuget-gallery-gateway** provides NuGet packages from the NuGet Gallery.
+ **pypi-gateway** provides Python packages from the Python Package Index.
# Configuring and using package repositories
In CodeCatalyst, packages are stored and managed inside package repositories. To publish packages to CodeCatalyst or to consume packages from a CodeCatalyst (or any supported public package repositories), you must create a package repository and connect your package manager to it.
**Topics**
+ [Creating a package repository](packages-repositories-create.md)
+ [Connecting to a package repository](packages-repositories-connect.md)
+ [Deleting a package repository](packages-repositories-delete.md)
# Creating a package repository
Perform the following steps to create a package repository in CodeCatalyst.
**To create a package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project in which you want to create a package repository.
1. From the navigation pane, choose **Packages**.
1. On the **Package repositories** page, choose **Create package repository**.
1. In the **Package repository details** section, add the following:
1. **Repository name**. Consider using a descriptive name with details such as your project or team name, or how the repository will be used.
1. (Optional) **Description**. A repository description is especially helpful when you have multiple repositories across multiple teams in a project.
1. In the **Upstream repositories** section, choose **Select upstream repositories** to add any package repositories that you want to access through your CodeCatalyst package repository. You can add **Gateway repositories** to connect to external package repositories or other **CodeCatalyst repositories**.
1. When a package is requested from a package repository, upstream repositories will be searched in the order they appear in this list. Once a package is found, CodeCatalyst will stop searching. To change the order of the upstream repositories, you can drag and drop the repositories in the list.
1. Choose **Create** to create your package repository.
# Connecting to a package repository
To publish to, or consume packages from CodeCatalyst, you must configure your package manager with your package repository endpoint information and CodeCatalyst credentials. If you haven't created a repository, you can do so by following the instructions in [Creating a package repository](packages-repositories-create.md).
For instructions on how to connect a package manager to a CodeCatalyst package repository, see the following documentation.
+ [Configuring and using Gradle Groovy](packages-maven-gradle.md)
+ [Configuring and using mvn](packages-maven-mvn.md)
+ [Configuring and using the nuget or dotnet CLI](packages-nuget-cli.md)
+ [Configuring and using npm](packages-npm-use.md)
+ [Configuring pip and installing Python packages](packages-python-pip.md)
+ [Configuring Twine and publishing Python packages](packages-python-twine.md)
# Deleting a package repository
Perform the following steps to delete a package repository in CodeCatalyst.
**To delete a package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project that contains the package repository that you want to delete.
1. From the navigation pane, choose **Packages**.
1. On the **Package repositories** page, choose the repository you want to delete.
1. Choose **Delete**.
1. Review the information provided about the effects of deleting a package repository.
1. Enter `delete` into the input field and choose **Delete**.
# Configuring and using upstream repositories
You can connect both gateway repositories, and other CodeCatalyst package repositories, as upstreams to your package repositories. This enables a package manager client to access the packages that are contained in more than one package repository by using a single package repository endpoint. The following are the main benefits of using upstream repositories:
+ You only have to configure your package manager with a single repository endpoint to pull from multiple sources.
+ Packages consumed from an upstream repository are stored in your downstream repository, which ensures your packages are available even if the upstream repository experiences unexpected outages or packages in the upstream repository are deleted.
You can add upstream repositories when you create a package repository. You can also add or remove upstream repositories from existing package repositories in the CodeCatalyst console.
When you add a gateway repository as an upstream repository, the package repository is connected to the gateway repository's corresponding public package repository. For a list of supported public package repositories, see [Supported external package repositories and their gateway repositories](packages-connect-external.md#packages-upstream-repositories-supported-external).
You can link multiple repositories together as upstream repositories. For example, suppose that your team creates a repository named `project-repo` and is already using another repository named `team-repo` that has the **npm-public-registry-gateway** added as an upstream repository, which is connected to the public npm repository, `npmjs.com`. You can add `team-repo` as an upstream repository to `project-repo`. In this case, you only have to configure your package manager to use `project-repo` to pull packages from `project-repo`, `team-repo`, `npm-public-registry-gateway`, and `npmjs.com`.
**Topics**
+ [Adding an upstream repository](packages-upstream-repositories-add.md)
+ [Editing the search order of upstream repositories](packages-upstream-repositories-search-order.md)
+ [Requesting a package version with upstream repositories](packages-upstream-repositories-request.md)
+ [Removing an upstream repository](packages-upstream-repositories-remove.md)
# Adding an upstream repository
Adding a public package repository or another CodeCatalyst package repository as an upstream repository to your downstream repository makes all of the packages in the upstream repository available to package managers that are connected to the downstream repository.
**To add an upstream repository**
1. In the navigation pane, choose **Packages**.
1. On the **Package repositories** page, choose the package repository that you want to add an upstream repository to.
1. Under the package repository's name, choose **Upstreams** and choose **Select upstream repositories**.
1. In **Select upstream type**, choose one of the following:
+ **Gateway repositories**
You can choose from a list of available gateway repositories.
**Note**
To connect to public external package authorities such as Maven Central, npmjs.com, or Nuget Gallery, CodeCatalyst uses gateway repositories as intermediary repositories that search and store packages pulled from external repositories. This saves time and data transfer as all package repositories in a project will use packages from the gateway intermediary repository. For more information, see [Connecting to public external repositories](packages-connect-external.md).
+ **CodeCatalyst repositories**
You can choose from a list of available CodeCatalyst package repositories in your project.
1. When you've selected all of the repositories you want to add as upstream repositories, choose **Select**, and then choose **Save**.
For more information about changing the search order of upstream repositories, see [Editing the search order of upstream repositories](packages-upstream-repositories-search-order.md).
When you've added an upstream repository, you can use a package manager that is connected to your local repository to fetch packages from the upstream repository. You do not need to update your package manager configuration. For more information about requesting package versions from an upstream repository, see [Requesting a package version with upstream repositories](packages-upstream-repositories-request.md).
# Editing the search order of upstream repositories
CodeCatalyst searches upstream repositories in their configured search order. When a package is found, CodeCatalyst stops searching. You can change the order in which the upstream repositories are searched for packages.
**To edit the search order of upstream repositories**
1. In the navigation pane, choose **Packages**.
1. On the **Package repositories** page, choose the package repository whose upstream repository search order you want to edit.
1. Under the package repository's name, choose **Upstreams**.
1. In the **Upstream repositories** section, you can view the upstream repositories and their search order. To change the search order, drag and drop the repositories in the list.
1. When you're finished editing the search order of upstream repositories, choose **Save**.
# Requesting a package version with upstream repositories
The following example shows the possible scenarios when a package manager requests a package from a CodeCatalyst package repository that has upstream repositories.
For this example, a package manager, such as `npm`, requests a package version from a package repository named `downstream` that has multiple upstream repositories. When the package is requested, the following can occur:
+ If `downstream` contains the requested package version, it is returned to the client.
+ If `downstream` does not contain the requested package version, CodeCatalyst searches for it in `downstream`'s upstream repositories, in their configured search order. If the package version is found, a reference to it is copied to `downstream`, and the package version is returned to the client.
+ If neither `downstream` or its upstream repositories contain the package version, an HTTP 404 `Not Found` response is returned to the client.
The maximum number of direct upstream repositories allowed for one repository is 10. The maximum number of repositories CodeCatalyst searches in when a package version is requested is 25.
## Package retention from upstream repositories
If a requested package version is found in an upstream repository, a reference to it is retained and is always available in the repository that requested it. This ensures that you have access to your packages if there is an unexpected outage of the upstream repository. The retained package version is not affected by any of the following:
+ Deleting the upstream repository.
+ Disconnecting the upstream repository from the downstream repository.
+ Deleting the package version from the upstream repository.
+ Editing the package version in the upstream repository (for example, by adding a new asset to it).
## Fetching packages through an upstream relationship
CodeCatalyst can fetch packages through multiple linked repositories called upstream repositories. If a CodeCatalyst package repository has an upstream connection to another CodeCatalyst package repository that has an upstream connection to a gateway repository, requests for packages not in the upstream repository are copied from the external repository. For example, consider the following configuration: a repository named `repo-A` has an upstream connection to the gateway repository, `npm-public-registry-gateway`. `npm-public-registry-gateway` has an upstream connection to the public package repository, [https://npmjs.com](https://npmjs.com).
![\[Simple upstream repository diagram showing three repositories chained together.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/packages/upstream-with-external.png)
If `npm` is configured to use the `repo-A` repository, running `npm install` initiates the copying of packages from [https://npmjs.com](https://npmjs.com) into `npm-public-registry-gateway`. The versions installed are also pulled into `repo-A`. The following example installs `lodash`.
```
$ npm config get registry
https://packages.region.codecatalyst.aws/npm/space-name/proj-name/repo-name/
$ npm install lodash
+ lodash@4.17.20
added 1 package from 2 contributors in 6.933s
```
After running `npm install`, `repo-A` contains only the latest version (`lodash 4.17.20`) because that's the version that was fetched by `npm` from `repo-A`.
Because `npm-public-registry-gateway` has an external upstream connection to [https://npmjs.com](https://npmjs.com), all the package versions that are imported from [https://npmjs.com](https://npmjs.com) are stored in `npm-public-registry-gateway`. These package versions could have been fetched by any downstream repository with an upstream connection that leads to `npm-public-registry-gateway`.
The contents of `npm-public-registry-gateway` provide a way for you to see all the packages and package versions imported from [https://npmjs.com](https://npmjs.com) over time.
## Package retention in intermediate repositories
CodeCatalyst allows you to chain upstream repositories. For example, `repo-A` can have `repo-B` as an upstream repository and `repo-B` can have `repo-C` as an upstream repository. This configuration makes the package versions in `repo-B` and `repo-C` available from `repo-A`.
![\[Simple upstream repository diagram showing three repositories chained together.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/packages/upstream-chaining.png)
When a package manager connects to repository `repo-A` and fetches a package version from repository `repo-C`, the package version is not retained in repository `repo-B`. The package version is only retained in the furthest downstream repository, which in this example is `repo-A`. It is not retained in any intermediate repositories. This is also true for longer chains; for example, if there were four repositories: `repo-A`, `repo-B`, `repo-C`, and `repo-D`, and a package manager connected to `repo-A` fetched a package version from `repo-D`, the package version would be retained in `repo-A` but not in `repo-B` or `repo-C`.
Package retention behavior is similar when pulling a package version from a public package repository, except that the package version is always retained in the gateway repository that has the direct upstream connection to the public repository. For example, `repo-A` has `repo-B` as an upstream repository. `repo-B` has `npm-public-registry-gateway` as an upstream repository, which has an upstream connection to the public repository, **npmjs.com**; see the diagram below.
![\[Upstream repository diagram showing three repositories chained together with an external upstream connection to npmjs.com.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/packages/upstream-chaining-external.png)
If a package manager connected to `repo-A` requests a specific package version, *lodash 4.17.20* for example, and the package version is not present in any of the three repositories, it will be fetched from **npmjs.com**. When *lodash 4.17.20* is fetched, it is retained in `repo-A` as that is the furthest downstream repository and `npm-public-registry-gateway` as it has the upstream connection to the public external repository, **npmjs.com**. *lodash 4.17.20* is not retained in `repo-B` because that is an intermediate repository.
# Removing an upstream repository
If you no longer want to access the packages within an upstream repository, you can remove the upstream repository from a package repository.
**Warning**
When you remove an upstream repository, you could break upstream relationship chains, which could break your projects or builds.
**To remove an upstream repository**
1. In the navigation pane, choose **Packages**.
1. On the **Package repositories** page, choose the package repository from which you want to remove an upstream repository.
1. Under the package repository's name, choose **Upstreams**.
1. In the **Edit upstream repositories** section, find the upstream repository you want to remove and choose ![\[Remove\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/packages/remove.png).
1. When you're finished removing upstream repositories, choose **Save**.
# Connecting to public external repositories
You can connect CodeCatalyst package repositories to supported public, external repositories by adding the corresponding gateway repository as an upstream repository. Gateway repositories act as intermediary repositories that search and store packages pulled from external repositories. This saves time and data transfer because all package repositories in a project can use stored packages from the gateway repository.
**To connect to a public repository using gateway repositories**
1. In the navigation pane, choose **Packages**.
1. In **Packages**, choose the **Gateway repositories** page. You can view a list of supported gateway repositories and their descriptions.
1. To use a gateway repository, first you must create it. If the gateway repository has been created, the date and time it was created is shown. If it hasn't, choose **Create** to create it.
1. To use packages from the gateway repository, you must set an upstream connection to it from a CodeCatalyst repository. Choose **Package repositories** and choose the package repository that you want to connect to.
1. To connect to the public repository, choose **Upstreams** and choose **Select upstream repositories**.
1. Choose **Gateway repositories** select the gateway repository that corresponds to the public repository that you want to connect to as an upstream repository .
1. When you've selected all of the gateway repositories you want to add as upstream repositories, choose **Select**.
1. When you're finished ordering upstream repositories, choose **Save**.
For more information about upstream repositories, see [Configuring and using upstream repositories](packages-upstream-repositories.md).
When you've added a gateway repository as an upstream repository, you can use a package manager that is connected to your local repository to fetch packages from the public, external package repository that corresponds to it. You do not need to update your package manager configuration. Packages consumed in this manner are stored in both the gateway repository and your local package repository. For more information about requesting package versions from an upstream repository, see [Requesting a package version with upstream repositories](packages-upstream-repositories-request.md).
## Supported external package repositories and their gateway repositories
CodeCatalyst supports adding an upstream connection to the following official package authorities with gateway repositories.
| Repository package type | Description | Gateway repository name |
| --- | --- | --- |
| npm | npm public registry | npm-public-registry-gateway |
| Python | Python Package Index | pypi-gateway |
| Maven | Maven Central | maven-central-gateway |
| Maven | Google Android repository | google-android-gateway |
| Maven | CommonsWare | commonsware-gateway |
| Maven | Gradle plugins repository | gradle-plugins-gateway |
| NuGet | NuGet Gallery | nuget-gallery-gateway |
# Publishing and modifying packages
A *package* in CodeCatalyst is a bundle of software and the metadata that is required to resolve dependencies and install the software. For a list of supported package formats in CodeCatalyst, see [Publish and share software packages in CodeCatalyst](packages.md). This section provides information about publishing, viewing, deleting packages, and updating a package version's status.
**Topics**
+ [Publishing packages to a CodeCatalyst package repository](package-publishing.md)
+ [Viewing package version details](working-with-packages-view.md)
+ [Deleting a package version](working-with-packages-delete.md)
+ [Updating a package version's status](working-with-packages-update-version-status.md)
+ [Editing package origin controls](package-origin-controls.md)
# Publishing packages to a CodeCatalyst package repository
You can publish versions of any supported package type to a CodeCatalyst package repository by using package manager tools. The steps to publish a package version are as follows:
**To publish a package version to a CodeCatalyst package repository**
1. If you haven't, [create a package repository](packages-repositories-create.md).
1. Connect your package manager to your package repository. For instructions on how to connect the npm package manager to a CodeCatalyst package repository, see [Configuring and using npm](packages-npm-use.md).
1. Use your connected package manager to publish your package versions.
**Contents**
+ [Publishing and upstream repositories](#package-publishing-upstreams)
+ [Private packages and public repositories](#package-publishing-upstreams-direct)
+ [Overwriting package assets](#package-publishing-overwrite-assets)
## Publishing and upstream repositories
In CodeCatalyst, you cannot publish package versions that are present in reachable upstream repositories or public repositories. For example, suppose that you want to publish an npm package, `lodash@1.0`, to a package repository, `myrepo`, and `myrepo` is connected to npmjs.com through a gateway repository configured as an upstream repository. If `lodash@1.0` is present in the upstream repository or in npmjs.com, CodeCatalyst rejects any attempt to publish to it in `myrepo` by issuing a 409 conflict error. This helps prevent you from accidentally publishing a package with the same name and version as a package in an upstream repository, which can result in unexpected behavior.
You can still publish different versions of a package name that exist in an upstream repository. For example, if `lodash@1.0` is present in an upstream repository, but `lodash@1.1` is not, you can publish `lodash@1.1` to the downstream repository.
## Private packages and public repositories
CodeCatalyst does not publish packages stored in CodeCatalyst repositories to public repositories, such as npmjs.com or Maven Central. CodeCatalyst imports packages from public repositories into a CodeCatalyst repository, but it doesn't move packages in the opposite direction. Packages that you publish to CodeCatalyst repositories remain private and are only available to the CodeCatalyst project in which the repository belongs.
## Overwriting package assets
You can't republish a package asset that already exists with different content. For example, suppose that you already published a Maven package with a JAR asset `mypackage-1.0.jar`. You can only publish that asset again if the checksum of the old and new assets are identical. To republish the same asset with new content, delete the package version first. Trying to republish the same asset name with different content will result in an HTTP 409 conflict error.
For package formats that support multiple assets (Python and Maven), you can add new assets with different names to an existing package version at any time, assuming you have the required permissions. Because npm and NuGet only support a single asset per package version, to modify a published package version you must first delete it.
If you try to republish an asset that already exists (for example, `mypackage-1.0.jar`), and the content of the published asset and the new asset are identical, the operation will succeed because the operation is idempotent.
# Viewing package version details
You can use the CodeCatalyst console to view details about a specific package version.
**To view package version details**
1. In the navigation pane, choose **Packages**.
1. On the **Package repositories** page, choose the repository that contains the package version that you want to view the details of.
1. Search for the package version in the **Packages** table. You can use the search bar to filter packages by package name and format. Choose the package from the list.
1. In the **Package details** page, choose **Versions**, and then choose the version you want to view.
# Deleting a package version
You can delete a package version from the **Package version details** page in the CodeCatalyst console.
**To delete a package version**
1. In the navigation pane, choose **Packages**.
1. On the **Package repositories** page, choose the repository that contains the package version that you want to delete.
1. Search and choose the package from the table.
1. On the **Package details** page, choose **Versions** and choose the version you want to delete.
1. On the **Package version details** page, choose **Version actions** and then choose **Delete**.
1. Enter *delete* into the text field and choose **Delete**.
# Updating a package version's status
Every package version in CodeCatalyst has a status that describes the current state and availability of the package version. You can change the package version status in the CodeCatalyst console. For more information about the possible status values of package versions and their meanings, see [Package version status](#package-version-status).
**To update a package version's status**
1. In the navigation pane, choose **Packages**.
1. On the **Package repositories** page, choose the repository that contains the package version that you want to update the status of.
1. Search and choose the package from the table.
1. On the **Package details** page, choose **Versions** and then choose the version that you want to view.
1. On the **Package version details** page, choose **Actions** and then choose **Unlist**, **Archive**, or **Dispose**. For information about each package version status, see [Package version status](#package-version-status).
1. Enter the confirmation text into the text field, and then choose **Unlist**, **Archive**, or **Dispose**, depending on which status you are updating to.
## Package version status
The following are possible values for package version status. You can change the package version status in the console. For more information, see [Updating a package version's status](#working-with-packages-update-version-status).
+ **Published**: The package version is successfully published and can be requested by a package manager. The package version will be included in package version lists returned to package managers; for example, in the output of `npm view versions`. All assets of the package version are available from the repository.
+ **Unfinished**: The last attempt to publish did not complete. Currently only Maven package versions can have a status of **Unfinished**. This can occur when the client uploads one or more assets for a package version but does not publish a `maven-metadata.xml` file for the package that includes that version.
+ **Unlisted**: The package version assets are available for download from the repository, but the package version is not included in the list of versions returned to package managers. For example, for an npm package, the output of `npm view versions` does not include the package version. This means that the npm dependency resolution logic does not select the package version because the version does not appear in the list of available versions. However, if the **Unlisted** package version is already referenced in an `npm package-lock.json` file, it can still be downloaded and installed; for example, when running `npm ci`.
+ **Archived**: The package version assets cannot be downloaded. The package version will not be included in the list of versions returned to package managers. Because the assets are not available, consumption of the package version by clients is blocked. If your application build depends on a version that is updated to **Archived**, the build will fail, unless the package version has been locally cached. You can't use a package manager or build tool to republish an **Archived** package version because it is still present in the repository. However, you can change the package version status back to **Unlisted** or **Published** in the console.
+ **Disposed**: The package version doesn't appear in listings, and the assets cannot be downloaded from the repository. The key difference between **Disposed** and **Archived** is that with a status of **Disposed**, the assets of the package version are permanently deleted by CodeCatalyst. For this reason, you cannot move a package version from **Disposed** to **Archived**, **Unlisted**, or **Published**. The package version cannot be used because the assets have been deleted. When a package version has been marked as **Disposed**, you are not billed for storage of the package assets.
In addition to the statuses in the preceding list, a package version can also be deleted. After it is deleted, a package version is not in the repository and you can freely republish that package version by using a package manager or build tool.
## Package name, package version, and asset name normalization
CodeCatalyst normalizes package names, package versions, and asset names before storing them, which means the names or versions in CodeCatalyst may be different than the name or version provided when the package was published. For more information about how names and versions are normalized in CodeCatalyst for each package type, see the following documentation.
+ [Python package name normalization](python-name-normalization.md)
+ [NuGet package name, version, and asset name normalization](nuget-name-normalization.md)
CodeCatalyst does not perform normalization on other package formats.
# Editing package origin controls
In Amazon CodeCatalyst, package versions can be added to a package repository by directly publishing them, pulling them down from an upstream repository, or ingesting them from an external, public repository through a gateway. If you allow versions of a package to be added both by direct publishing and ingesting from public repositories, then you are vulnerable to a dependency substitution attack. For more information, see [Dependency substitution attacks](#dependency-substitution-attacks). To protect yourself against a dependency substitution attack, configure package origin controls on a package in a repository to limit how versions of that package can be added to the repository.
You should consider configuring package origin controls to make new versions of different packages come from both internal sources, such as direct publishing, and external sources, such as public repositories. By default, package origin controls are configured based on how the first version of a package is added to the repository.
## Package origin control settings
With package origin controls, you can configure how package versions can be added to a repository. The following lists include the available package origin control settings and values.
**Publish**
This setting configures whether package versions can be published directly to the repository using package managers or similar tools.
+ **ALLOW**: Package versions can be published directly.
+ **BLOCK**: Package versions cannot be published directly.
**Upstream**
This setting configures whether package versions can be ingested from external, public repositories, or retained from upstream repositories when requested by a package manager.
+ **ALLOW**: Any package version can be retained from other CodeCatalyst repositories configured as upstream repositories or ingested from a public source with an external connection.
+ **BLOCK**: Package versions cannot be retained from other CodeCatalyst repositories configured as upstream repositories or ingested from a public source with an external connection.
### Default package origin control settings
The default package origin controls for a package will be based on how the first version of that package is added to the package repository.
+ If the first package version is published direcly by a package manager, the settings will be **Publish: ALLOW** and **Upstream: BLOCK**.
+ If the first package version is ingested from a public source, the settings will be **Publish: BLOCK** and **Upstream: ALLOW**.
## Common package access control scenarios
This section describes some common scenarios of when a package version is added to a CodeCatalyst package repository. Package origin control settings are set for new packages depending on how the first package version is added.
In the following scenarios, an *internal package* is published directly from a package manager to your repository, such as a package that you maintain. An *external package* is a package that exists in a public repository that can be ingested into your repository through a gateway repository upstream.
**An external package version is published for an existing internal package**
In this scenario, consider an internal package, *packageA*. Your team publishes the first package version for *packageA* to a CodeCatalyst package repository. Because this is the first package version for that package, the package origin control settings are automatically set to **Publish: Allow** and **Upstream: Block**. After the package is published in your repository, a package with the same name is published to a public repository that is connected to your CodeCatalyst package repository. This could be an attempted dependency substitution attack against the internal package, or it could be a coincidence. Regardless, package origin controls are configured to block the ingestion of the new external version to protect themselves against a potential attack.
In the following image, *repoA* is your CodeCatalyst package repository with an upstream connection to the `npm-public-registry-gateway` repository. Your repository contains versions 1.1 and 2.1 of *packageA*, but version 3.0 is published to the public repository. Normally, *repoA* would ingest version 3.0 after the package is requested by a package manager. Because package ingestion is set to **Block**, version 3.0 is not ingested into your CodeCatalyst package repository and is not available to package managers connected to it.
![\[Simple graphic showing a new external package version being blocked from a public repository.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/packages/package-origin-controls-one.png)
**An internal package version is published for an existing external package**
In this scenario, a package, *packageB*, exists externally in a public repository that you have connected to your repository. When a package manager connected to your repository requests *packageB*, the package version is ingested into your repository from the public repository. Because this is the first package version of *packageB* added to your repository, the package origin settings are configured to **Publish: BLOCK** and **Upstream: ALLOW**. Later, you try to publish a version with the same package name to the repository. You may not be aware of the public package and trying to publish an unrelated package by same name, or you may be trying to publish a patched version, or you may be trying to directly publish the exact package version that already exists externally. CodeCatalyst rejects the version that you are trying to publish, but you can explicitly override the rejection and publish the version, if necessary.
In the following image, *repoA* is your CodeCatalyst package repository with an upstream connection to the `npm-public-registry-gateway` repository. Your package repository contains version 3.0 that it ingested from the public repository. You want to publish version 1.2 to your package repository. Typically, you could publish version 1.2 to *repoA*, but because publishing is set to **Block**, version 1.2 cannot be published.
![\[Simple graphic showing package publishing blocked.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/packages/package-origin-controls-two.png)
**Publishing a patched package version of an existing external package**
In this scenario, a package, *packageB*, exists externally in a public repository that you have connected to your package repository. When a package manager connected to your repository requests *packageB*, the package version is ingested into your repository from the public repository. Because this is the first package version of *packageB* added to your repository, the package origin settings are configured to **Publish: BLOCK** and **Upstream: ALLOW**. Your team decides to publish patched package versions of this package to the repository. To be able to publish package versions directly, your team changes the package origin control settings to **Publish: ALLOW** and **Upstream: BLOCK**. Versions of this package can now be published directly to your repository and ingested from public repositories. After your team publishes the patched package versions, your team reverts the package origin settings to **Publish: BLOCK** and **Upstream: ALLOW**.
## Editing package origin controls
Package origin controls are configured automatically based on how the first package version of a package is added to the package repository. For more information, see [Default package origin control settings](#default-package-origin-control-settings). To add or edit package origin controls for a package in a CodeCatalyst package repository, perform the steps in the following procedure.
**To add or edit package origin controls**
1. In the navigation pane, choose **Packages**.
1. Choose the package repository that contains the package that you want to edit.
1. In the **Packages** table, search for and choose the package that you want to edit.
1. From the package summary page, choose **Origin controls**.
1. In **Origin controls**, choose the package origin controls that you want to set for this package. Both package origin control settings, **Publish** and **Upstream**, must be set at the same time.
+ To allow publishing package versions directly, in **Publish**, choose **Allow**. To block publishing of package versions, choose **Block**.
+ To allow ingestion of packages from external repositories and pulling packages from upstream repositories, in **Upstream sources**, choose **Allow**. To block all ingestion and pulling of package versions from external and upstream repositories, choose **Block**.
1. Choose **Save**.
## Publishing and upstream repositories
In CodeCatalyst, you cannot publish package versions that are present in reachable upstream repositories or public repositories. For example, suppose that you want to publish an npm package `lodash@1.0` to a repository, `myrepo`, and `myrepo` has an upstream repository with an external connection to npmjs.com. Consider the following scenarios.
1. The package origin control settings on `lodash` are **Publish: ALLOW** and **Upstream: ALLOW**. If `lodash@1.0` is present in the upstream repository or in npmjs.com, CodeCatalyst rejects any attempt to publish to it in `myrepo` by issuing a 409 conflict error. You could still publish a different version, such as `lodash@1.1`.
1. The package origin control settings on `lodash` are **Publish: ALLOW** and **Upstream: BLOCK**. You can publish any version of `lodash` to your repository that does not already exist because package versions are not reachable.
1. The package origin control settings on `lodash` are **Publish: BLOCK** and **Upstream: ALLOW**. You cannot publish any package versions directly to your repository.
## Dependency substitution attacks
Package managers simplify the process of packaging and sharing reusable code. These packages may be private packages developed by an organization for use in their applications, or they may be public, typically open-source packages that are developed outside an organization and distributed by public package repositories. When requesting packages, developers rely on their package manager to fetch new versions of their dependencies. Dependency substitution attacks, also known as dependency confusion attacks, exploit the fact that a package manager typically has no way to distinguish legitimate versions of a package from malicious versions.
Dependency substitution attacks belong to a subset of attacks known as software supply chain attacks. A software supply chain attack is an attack that takes advantage of vulnerabilities anywhere in the software supply chain.
A dependency substitution attack can target anyone who uses both internally developed packages and packages fetched from public repositories. The attackers identify internal package names and then strategically place malicious code with the same name in public package repositories. Typically, the malicious code is published in a package with a high version number. Package managers fetch the malicious code from these public feeds because they believe that the malicious packages are the latest versions of the package. This causes a "confusion" or "substitution" between the desired package and the malicious package, which leads to the code being compromised.
To prevent dependency substitution attacks, Amazon CodeCatalyst provides package origin controls. Package origin controls are settings that control how packages can be added to your repositories. The controls are configured automatically when the first package version of a new package is added to a CodeCatalyst repository The controls can ensure package versions cannot be both published directly to your repository and ingested from public sources, protecting you from dependency substitution attacks. For more information about package origin controls and how to change them, see [Editing package origin controls](#package-origin-controls).
# Using npm
These topics describe how you can use `npm`, the Node.js package manager, with CodeCatalyst.
**Note**
CodeCatalyst supports `node v4.9.1` and later and `npm v5.0.0` and later.
**Topics**
+ [Configuring and using npm](packages-npm-use.md)
+ [npm tag handling](packages-npm-tags.md)
# Configuring and using npm
To use `npm` with CodeCatalyst, you must connect `npm` to your package repository and provide a personal access token (PAT) for authentication. You can view instructions for connecting `npm` to your package repository in the CodeCatalyst console.
**Contents**
+ [Configuring npm with CodeCatalyst](#npm-configure)
+ [Installing npm packages from a CodeCatalyst package repository](#npm-install)
+ [Installing npm packages from npmjs through CodeCatalyst](#npm-install-npmjs)
+ [Publishing npm packages to your CodeCatalyst package repository](#npm-publish)
+ [npm command support](#npm-commands)
+ [Supported commands that interact with a package repository](#supported-commands-that-interact-with-a-repository)
+ [Supported client-side commands](#supported-client-side-commands)
+ [Unsupported commands](#unsupported-commands)
## Configuring npm with CodeCatalyst
The following instructions explain how to authenticate and connect `npm` to your CodeCatalyst package repository. For more information about npm, see the [official npm documentation](https://docs.npmjs.com/).
**To connect `npm` to your CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to your project.
1. In the navigation pane, choose **Packages**.
1. Choose your package repository from the list.
1. Choose **Connect to repository**.
1. In **Configuration details**, in **Package manager client**, choose **npm client**.
1. Choose your operating system to view the corresponding configuration steps.
1. A personal access token (PAT) is required to authenticate npm with CodeCatalyst. If you already have a token, you can use it. If not, you can create one using the following steps.
1. **(Optional):** Update the **PAT name** and **Expiration date**.
1. Choose **Create token**.
1. Copy and store your PAT in a safe location.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box. Credentials should be short lived to minimize the length of time an attacker can use the credentials after misappropriating them.
1. Run the following commands from your project's root directory to configure npm with your package repository. The commands will do the following:
+ Create a project-level `.npmrc` file if your project does not have one.
+ Add the package repository endpoint information to your project-level `.npmrc` file.
+ Add your credentials (PAT) to your user-level `.npmrc` file.
Replace the following values.
**Note**
If you are copying from the console instructions, the values in the following commands are updated for you and do not need to be changed.
+ Replace *username* with your CodeCatalyst user name.
+ Replace *PAT* with your CodeCatalyst PAT.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
```
npm set registry=https://packages.region.codecatalyst.aws/npm/space-name/proj-name/repo-name/ --location project
npm set //packages.region.codecatalyst.aws/npm/space-name/proj-name/repo-name/:_authToken=username:PAT
```
**For npm 6 or lower:** To make npm always pass the auth token to CodeCatalyst, even for `GET` requests, set the always-auth configuration variable with `npm config set` as follows.
```
npm set //packages.region.codecatalyst.aws/npm/space-name/proj-name/repo-name/:always-auth=true --location project
```
## Installing npm packages from a CodeCatalyst package repository
After you connect npm to your repository by following the steps in [Configuring npm with CodeCatalyst](#npm-configure), you can run `npm` commands on your repository.
You can install an npm package that is in your CodeCatalyst package repository or one of its upstream repositories with the `npm install` command.
```
npm install lodash
```
## Installing npm packages from npmjs through CodeCatalyst
You can install npm packages from [npmjs.com](https://www.npmjs.com/) through a CodeCatalyst repository by configuring the repository with an upstream connection to the gateway repository connected to npmjs.com, **npm-public-registry-gateway**. Packages installed from npmjs are ingested and stored in the gateway repository, and the farthest downstream package repository.
**To install packages from npmjs**
1. If you haven't already done so, configure `npm` with your CodeCatalyst package repository by following the steps in [Configuring npm with CodeCatalyst](#npm-configure).
1. Check that your repository has added the gateway repository, **npm-public-registry-gateway**, as an upstream connection. You can check which upstream sources are added or add **npm-public-registry-gateway** as an upstream source by following the instructions in [Adding an upstream repository](packages-upstream-repositories-add.md) and choosing the **npm-public-registry-gateway** repository.
1. Install packages with the `npm install` command.
```
npm install package_name
```
For more information about requesting packages from upstream repositories, see [Requesting a package version with upstream repositories](packages-upstream-repositories-request.md).
## Publishing npm packages to your CodeCatalyst package repository
After you have completed [Configuring npm with CodeCatalyst](#npm-configure), you can run `npm` commands.
You can publish an npm package to a CodeCatalyst package repository with the `npm publish` command.
```
npm publish
```
For information about how to create npm packages, see [Creating Node.js Modules](https://docs.npmjs.com/getting-started/creating-node-modules) on *npm Docs*.
## npm command support
The following sections summarize the `npm` commands that are supported by CodeCatalyst package repositories, in addition to listing specific commands that are not supported.
**Topics**
+ [Supported commands that interact with a package repository](#supported-commands-that-interact-with-a-repository)
+ [Supported client-side commands](#supported-client-side-commands)
+ [Unsupported commands](#unsupported-commands)
### Supported commands that interact with a package repository
This section lists `npm` commands where the `npm` client makes one or more requests to the registry to which it is configured (for example, `npm config set registry`). These commands have been verified to function correctly when invoked against a CodeCatalyst package repository.
****
| Command | Description |
| --- | --- |
| [bugs](https://docs.npmjs.com/cli/bugs) | Guesses the location of a package’s bug tracker URL, and then it attempts to open it. |
| [ci](https://docs.npmjs.com/cli/ci) | Installs a project with a clean slate. |
| [deprecate](https://docs.npmjs.com/cli/deprecate) | Deprecates a version of a package. |
| [dist-tag](https://docs.npmjs.com/cli/dist-tag) | Modifies package distribution tags. |
| [docs](https://docs.npmjs.com/cli/docs) | Guesses the location of a package’s documentation URL, and then it attempts to open it by using the `--browser` config parameter. |
| [doctor](https://docs.npmjs.com/cli/doctor) | Runs a set of checks to validate that your npm installation can manage your JavaScript packages. |
| [install](https://docs.npmjs.com/cli/install) | Installs a package. |
| [install-ci-test](https://docs.npmjs.com/cli/install-ci-test) | Installs a project with a clean slate and runs tests. Alias: `npm cit`. This command runs an `npm ci`, followed immediately by an `npm test`. |
| [install-test](https://docs.npmjs.com/cli/install-test) | Installs package and runs tests. Runs an `npm install`, followed immediately by an `npm test`. |
| [outdated](https://docs.npmjs.com/cli/outdated) | Checks the configured registry to determine if any installed packages are outdated. |
| [ping](https://docs.npmjs.com/cli/ping) | Pings the configured or given npm registry and verifies authentication. |
| [publish](https://docs.npmjs.com/cli/publish) | Publishes a package version to the registry. |
| [update](https://docs.npmjs.com/cli/update) | Guesses the location of a package’s repository URL, and then it attempts to open it by using the `--browser` config parameter. |
| [view](https://docs.npmjs.com/cli/view) | Displays package metadata. Can also be used to print metadata properties. |
### Supported client-side commands
These commands don't require any direct interaction with a package repository, so CodeCatalyst does not require anything to support them.
****
| Command | Description |
| --- | --- |
| [bin (legacy)](https://docs.npmjs.com/cli/v8/commands/npm-bin) | Displays the npm `bin` directory. |
| [build](https://docs.npmjs.com/cli/v6/commands/npm-build) | Builds a package. |
| [cache](https://docs.npmjs.com/cli/cache) | Manipulates the packages cache. |
| [completion](https://docs.npmjs.com/cli/completion) | Enables tab completion in all npm commands. |
| [config](https://docs.npmjs.com/cli/config) | Updates the contents of the user and global `npmrc` files. |
| [dedupe](https://docs.npmjs.com/cli/dedupe) | Searches the local package tree and attempts to simplify the structure by moving dependencies further up the tree where they can be more effectively shared by multiple dependent packages. |
| [edit](https://docs.npmjs.com/cli/edit) | Edits an installed package. Selects a dependency in the current working directory and opens the package directory in the default editor. |
| [explore](https://docs.npmjs.com/cli/explore) | Browses an installed package. Spawns a subshell in the directory of the specified installed package. If a command is specified, then it is run in the subshell, which then immediately shuts down. |
| [help](https://docs.npmjs.com/cli/help) | Gets help on npm. |
| [help-search](https://docs.npmjs.com/cli/help-search) | Searches npm help documentation. |
| [init](https://docs.npmjs.com/cli/init) | Creates a `package.json` file. |
| [link](https://docs.npmjs.com/cli/link) | Symlinks a package directory. |
| [ls](https://docs.npmjs.com/cli/ls) | Lists installed packages. |
| [pack](https://docs.npmjs.com/cli/pack) | Creates a tarball from a package. |
| [prefix](https://docs.npmjs.com/cli/prefix) | Displays a prefix. This is the closest parent directory to contain a `package.json` file, unless `-g` is also specified. |
| [prune](https://docs.npmjs.com/cli/prune) | Removes packages that are not listed on the parent package's dependencies list. |
| [rebuild](https://docs.npmjs.com/cli/rebuild) | Runs the `npm build` command on the matched folders. |
| [restart](https://docs.npmjs.com/cli/restart) | Runs a package's stop, restart, and start scripts and associated pre-scripts and post-scripts. |
| [root](https://docs.npmjs.com/cli/root) | Prints the effective `node_modules` directory to standard out. |
| [run-script](https://docs.npmjs.com/cli/run-script) | Runs arbitrary package scripts. |
| [shrinkwrap](https://docs.npmjs.com/cli/shrinkwrap) | Locks down dependency versions for publication. |
| [uninstall](https://docs.npmjs.com/cli/uninstall) | Uninstalls a package. |
### Unsupported commands
These `npm` commands are not supported by CodeCatalyst package repositories.
****
| Command | Description | Notes |
| --- | --- | --- |
| [access](https://docs.npmjs.com/cli/access) | Sets the access level on published packages. | CodeCatalyst uses a permission model that is different from the public npmjs repository. |
| [adduser](https://docs.npmjs.com/cli/adduser) | Adds a registry user account | CodeCatalyst uses a user model that is different from the public npmjs repository. |
| [audit](https://docs.npmjs.com/cli/audit) | Runs a security audit. | CodeCatalyst does not currently vend security vulnerability data. |
| [hook](https://docs.npmjs.com/cli/v9/commands/npm-hook) | Manages npm hooks, including adding, removing, listing, and updating. | CodeCatalyst does not currently support any change notification mechanism. |
| [login](https://docs.npmjs.com/cli-commands/adduser.html) | Authenticates a user. This is an alias for `npm adduser`. | CodeCatalyst uses an authentication model that is different from the public npmjs repository. For information, see [Configuring npm with CodeCatalyst](#npm-configure). |
| [logout](https://docs.npmjs.com/cli/logout) | Signs out of the registry. | CodeCatalyst uses an authentication model that is different from the public npmjs repository. There is no way to sign out from a CodeCatalyst repository, but authentication tokens expire after their configurable expiration time. The default token duration is 12 hours. |
| [owner](https://docs.npmjs.com/cli/owner) | Manages package owners. | CodeCatalyst uses a permissions model that is different from the public npmjs repository. |
| [profile](https://docs.npmjs.com/cli/profile) | Changes settings on your registry profile. | CodeCatalyst uses a user model that is different from the public npmjs repository. |
| [search](https://docs.npmjs.com/cli/search) | Searches the registry for packages matching the search terms. | CodeCatalyst does not support the `search` command. |
| [star](https://docs.npmjs.com/cli/star) | Marks your favorite packages. | CodeCatalyst currently does not support any favorites mechanism. |
| [stars](https://docs.npmjs.com/cli/stars) | Views packages marked as favorites. | CodeCatalyst currently does not support any favorites mechanism. |
| [team](https://docs.npmjs.com/cli/team) | Manages teams and team memberships. | CodeCatalyst uses a user and group membership model that is different from the public npmjs repository. |
| [token](https://docs.npmjs.com/cli/token) | Manages your authentication tokens. | CodeCatalyst uses a different model for getting authentication tokens. For information, see [Configuring npm with CodeCatalyst](#npm-configure). |
| [unpublish](https://docs.npmjs.com/cli/unpublish) | Removes a package from the registry. | CodeCatalyst does not support removing a package version from a repository by using the npm client. You can delete a package in the console. |
| [whoami](https://docs.npmjs.com/cli/whoami) | Displays the npm user name. | CodeCatalyst uses a user model that is different from the public npmjs repository. |
# npm tag handling
npm registries support *tags*, which are string aliases for package versions. You can use tags to provide an alias instead of using version numbers. For example, you have a project with multiple streams of development and you use a different tag for each stream (for example, `stable`, `beta`, `dev`, `canary`). For more information, see [dist-tag](https://docs.npmjs.com/cli/dist-tag) on *npm Docs*.
By default, npm uses the `latest` tag to identify the current version of a package. `npm install pkg` (without `@version` or `@tag` specifier) installs the latest tag. Typically, projects only use the latest tag for stable release versions. Other tags are used for unstable or prerelease versions.
## Editing tags with the npm client
The three `npm dist-tag` commands (`add`, `rm`, and `ls`) function the same way in CodeCatalyst package repositories as they function in the [default npm registry](https://registry.npmjs.com/).
## npm tags and upstream repositories
When `npm` requests the tags for a package and versions of that package are also present in an upstream repository, CodeCatalyst merges the tags before returning them to the client. For example, a repository named `R` has an upstream repository named `U`. The following table shows the tags for a package named `web-helper` that's present in both repositories.
****
| Repository | Package name | Package tags |
| --- | --- | --- |
| R | `web-helper` | *latest* (alias for version 1.0.0) |
| U | `web-helper` | *alpha* (alias for version 1.0.1) |
In this case, when the npm client fetches the tags for the `web-helper` package from repository `R`, it receives both the *latest* and *alpha* tags. The versions the tags point to won't change.
When the same tag is present on the same package in both the upstream and local repository, CodeCatalyst uses the tag that was *last updated*. For example, suppose that the tags on *webhelper* have been modified to look like the following.
****
| Repository | Package name | Package tags | Last updated |
| --- | --- | --- | --- |
| R | `web-helper` | *latest* (alias for version 1.0.0) | January 1, 2023 |
| U | `web-helper` | *latest* (alias for version 1.0.1) | June 1, 2023 |
In this case, when the npm client fetches the tags for package *web-helper* from repository `R`, the *latest* tag will alias the version *1.0.1* because it was updated last. This makes it easy to consume new package versions in an upstream repository that are not yet present in a local repository by running `npm update`.
# Using Maven
The Maven repository format is used by many different languages, including Java, Kotlin, Scala, and Clojure. It's supported by many different build tools, including Maven, Gradle, Scala SBT, Apache Ivy, and Leiningen.
We have tested and confirmed compatibility with CodeCatalyst for the following versions:
+ Latest **Maven** version: 3.6.3.
+ Latest **Gradle** version: 6.4.1. Version 5.5.1 has also been tested.
**Topics**
+ [Configuring and using Gradle Groovy](packages-maven-gradle.md)
+ [Configuring and using mvn](packages-maven-mvn.md)
+ [Publishing packages with curl](packages-maven-curl.md)
+ [Using Maven checksums and snapshots](packages-maven-checksums-snapshots.md)
# Configuring and using Gradle Groovy
To use Gradle Groovy with CodeCatalyst, you must connect Gradle Groovy to your package repository and provide a personal access token (PAT) for authentication. You can view instructions for connecting Gradle Groovy to your package repository in the CodeCatalyst console.
**Contents**
+ [Fetching dependencies from CodeCatalyst](#gradle-fetch-dependencies)
+ [Fetching plugins from CodeCatalyst](#gradle-fetch-plugins)
+ [Fetching packages from external package repositories through CodeCatalyst](#gradle-install-public)
+ [Publishing packages to CodeCatalyst](#gradle-publish-packages)
+ [Running a Gradle build in IntelliJ IDEA](#gradle-intellij)
+ [Method 1: Put the PAT in `gradle.properties`](#gradle-intellij-gradle-properties)
+ [Method 2: Put the PAT in a separate file](#gradle-intellij-file)
## Fetching dependencies from CodeCatalyst
The following instructions explain how to configure Gradle Groovy to fetch dependencies your CodeCatalyst package repository.
**To use Gradle Groovy to fetch dependencies from your CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to your project.
1. In the navigation pane, choose **Packages**.
1. Choose your package repository from the list of package repositories.
1. Choose **Connect to repository**.
1. In the **Connect to repository** dialog box, choose **Gradle Groovy** from the list of package manager clients.
1. You will need a personal access token (PAT) to authenticate Gradle Groovy with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.
1. Choose **Create token**.
1. Choose **Copy** to copy your PAT.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box.
1. Update your gradle properties file with your access credentials. Replace *username* with your CodeCatalyst username and replace *PAT* with your CodeCatalyst personal access token. You can use any value for *spaceUsername* and *spacePassword* as long as you use the same values in the following steps.
```
spaceUsername=username
spacePassword=PAT
```
1. To fetch dependencies from CodeCatalyst in a Gradle build, copy the `maven` code snippet and add it to the `repositories` section in your project's `build.gradle` file. Replace the following values. You can use any value for *spaceName* as long as you use the same values in the following steps.
**Note**
If copying from the console instructions, the following values should be updated for you and should not be changed.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
```
maven {
name = 'spaceName'
url = uri('https://packages.region.codecatalyst.aws/maven/space_name/proj_name/repo_name/')
credentials(PasswordCredentials)
}
```
1. (Optional) To use the CodeCatalyst package repository as the only source for your project dependencies, remove any other sections in repositories from the `build.gradle` file. If you have more than one repository, Gradle searches each repository for dependencies in the order they are listed.
## Fetching plugins from CodeCatalyst
By default Gradle will resolve plugins from the public [Gradle Plugin Portal](https://plugins.gradle.org/). The following steps configure your Gradle project to resolve plugins from your CodeCatalyst package repository.
**To use Gradle to fetch plugins from your CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to your project.
1. In the navigation pane, choose **Packages**.
1. Choose your package repository from the list of package repositories.
1. Choose **Connect to repository**.
1. In the **Connect to repository** dialog box, choose **Gradle** from the list of package manager clients.
1. You will need a personal access token (PAT) to authenticate Gradle with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.
1. Choose **Create token**.
1. Choose **Copy** to copy your PAT.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box.
1. Update your gradle properties file with your access credentials. Replace *username* with your CodeCatalyst username and replace *PAT* with your CodeCatalyst personal access token. You can use any value for *spaceUsername* and *spacePassword* as long as you use the same values in the following steps.
```
spaceUsername=username
spacePassword=PAT
```
1. Add a `pluginManagement` block to your `settings.gradle` file. The `pluginManagement` block must appear before any other statements in `settings.gradle`. Replace the following values.
**Note**
If copying from the console instructions, the following values should be updated for you and should not be changed.
+ Replace *spaceName* with the name value used in the previous step.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
```
pluginManagement {
repositories {
maven {
name = 'spaceName'
url = uri('https://packages.region.codecatalyst.aws/maven/space_name/proj_name/repo_name/')
credentials(PasswordCredentials)
}
}
}
```
This will ensure that Gradle resolves plugins from the specified repository. The repository must have an upstream connection configured to the Gradle Plugin Portal (`gradle-plugins-store`) so that commonly required Gradle plugins are available to the build. For more information, see the [Gradle documentation](https://docs.gradle.org/current/userguide/plugins.html#sec:custom_plugin_repositories).
## Fetching packages from external package repositories through CodeCatalyst
You can install Maven packages from public repositories through a CodeCatalyst repository by configuring it with an upstream connection to the gateway that represents the gateway repository. Packages installed from the gateway repository are ingested and stored in your CodeCatalyst repository.
CodeCatalyst supports the following public Maven package repositories.
+ maven-central-gateway
+ google-android-gateway
+ gradle-plugins-gateway
+ commonsware-gateway
**To install packages from public Maven package repositories**
1. If you haven't already, configure Gradle with your CodeCatalyst package repository by following the steps in [Fetching dependencies from CodeCatalyst](#gradle-fetch-dependencies) or [Fetching plugins from CodeCatalyst](#gradle-fetch-plugins).
1. Ensure that your repository has added the gateway repository you want to install from as an upstream connection. You can do this by following the instructions in [Adding an upstream repository](packages-upstream-repositories-add.md) and choosing the public package repository you want to add as an upstream.
For more information about requesting packages from upstream repositories, see [Requesting a package version with upstream repositories](packages-upstream-repositories-request.md).
## Publishing packages to CodeCatalyst
This section describes how to publish a Java library built with Gradle Groovy to a CodeCatalyst repository.
**To use Gradle Groovy to publish packages to a CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. On the overview page for your project, choose **Packages**.
1. Choose your package repository from the list of package repositories.
1. Choose **Connect to repository**.
1. In the **Connect to repository** dialog box, choose **Gradle Groovy** from the list of package manager clients.
1. You will need a personal access token (PAT) to authenticate Gradle with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.
1. Choose **Create token**.
1. Choose **Copy** to copy your PAT.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box.
1. Update your gradle properties file with your access credentials. Replace *username* with your CodeCatalyst username and replace *PAT* with your CodeCatalyst personal access token. You can use any value for *spaceUsername* and *spacePassword* as long as you use the same values in the following steps.
```
spaceUsername=username
spacePassword=PAT
```
1. Add the `maven-publish` plugin to the `plugins` section of the project's `build.gradle` file.
```
plugins {
id 'java-library'
id 'maven-publish'
}
```
1. Next, add a `publishing` section to the project `build.gradle` file. Replace the following values.
**Note**
If copying from the console instructions, the following values should be updated for you and should not be changed.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
```
publishing {
publications {
mavenJava(MavenPublication) {
groupId = 'group-id'
artifactId = 'artifact-id'
version = 'version'
from components.java
}
}
repositories {
maven {
name = 'spaceName'
url = uri('https://packages.region.codecatalyst.aws/maven/space_name/proj_name/repo_name/')
credentials(PasswordCredentials)
}
}
}
```
The `maven-publish` plugin generates a POM file based on the `groupId`, `artifactId`, and `version` specified in the `publishing` section.
1. After these changes to `build.gradle` are complete, run the following command to build the project and upload it to the repository.
```
./gradlew publish
```
1. Navigate to your package repository in the CodeCatalyst console to check that the package was successfully published. You should see the package in the **Packages** list of your package repository.
For more information, see these topics on the Gradle website:
+ [Building Java Libraries](https://guides.gradle.org/building-java-libraries/)
+ [Publishing a project as a module](https://docs.gradle.org/current/userguide/publishing_setup.html)
## Running a Gradle build in IntelliJ IDEA
You can run a Gradle build in IntelliJ IDEA that pulls dependencies from CodeCatalyst. To authenticate Gradle with CodeCatalyst, you must use a personal access token (PAT). You can store your CodeCatalyst PAT in `gradle.properties` or a separate file of your choice.
### Method 1: Put the PAT in `gradle.properties`
Use this method if you are not using the `gradle.properties` file and can overwrite its contents with your PAT. If you are using `gradle.properties`, you can modify this method to add the PAT instead of overwriting the file's contents.
**Note**
The example shows the `gradle.properties` file located in `GRADLE_USER_HOME`.
First, create a PAT if you do not have one.
**To create a personal access token (PAT)**
1. In the top menu bar, choose your profile badge, and then choose **My settings**.
**Tip**
You can also find your user profile by going to the members page for a project or space and choosing your name from the members list.
1. In **PAT name**, enter a descriptive name for your PAT.
1. In **Expiration date**, leave the default date or choose the calendar icon to select a custom date. The expiration date defaults to one year from the current date.
1. Choose **Create**.
You can also create this token when you choose **Clone repository** for a source repository.
1. Save the PAT secret in a secure location.
**Important**
The PAT secret only displays once. You cannot retrieve it after you close the window.
Next, update your `build.gradle` file with the following snippet:
```
repositories {
maven {
name = 'spaceName'
url = uri('https://packages.region.codecatalyst.aws/maven/space_name/proj_name/repo_name/')
credentials(PasswordCredentials)
}
}
```
### Method 2: Put the PAT in a separate file
Use this method if you do not want to modify your `gradle.properties` file.
First, create a PAT if you do not have one.
**To create a personal access token (PAT)**
1. In the top menu bar, choose your profile badge, and then choose **My settings**.
**Tip**
You can also find your user profile by going to the members page for a project or space and choosing your name from the members list.
1. In **PAT name**, enter a descriptive name for your PAT.
1. In **Expiration date**, leave the default date or choose the calendar icon to select a custom date. The expiration date defaults to one year from the current date.
1. Choose **Create**.
You can also create this token when you choose **Clone repository** for a source repository.
1. Save the PAT secret in a secure location.
**Important**
The PAT secret only displays once. You cannot retrieve it after you close the window.
**To put your PAT in a separate file**
1. Update your `build.gradle` file with the following snippet. Replace *space\$1name*, *proj\$1name*, and *repo\$1name* with your CodeCatalyst user name, space name, project name, and package repository name.
```
def props = new Properties()
file("fileName").withInputStream { props.load(it) }
repositories {
maven {
name = 'spaceName'
url = uri('https://packages.region.codecatalyst.aws/maven/space_name/proj_name/repo_name/')
credentials(PasswordCredentials)
}
}
}
```
1. Write your PAT into the file that was specified in your `build.gradle` file:
```
echo "codecatalystArtifactsToken=PAT" > fileName
```
# Configuring and using mvn
You use the `mvn` command to run Maven builds. You must configure `mvn` to use your package repository and provide a personal access token (PAT) for authentication.
**Contents**
+ [Fetching dependencies from CodeCatalyst](#mvn-fetch-dependencies)
+ [Fetching packages from external package repositories through CodeCatalyst](#mvn-install-public)
+ [Publishing packages to CodeCatalyst](#mvn-publish-packages)
+ [Publishing third-party packages](#publishing-third-party-packages)
## Fetching dependencies from CodeCatalyst
To configure `mvn` to fetch dependencies from a CodeCatalyst repository, you must edit the Maven configuration file, `settings.xml` and optionally, your project's Project Model Object (POM) file. The POM file contains information about the project and configuration information for Maven to build the project such as dependencies, build directory, source directory, test source directory, plugin, and goals.
**To use `mvn` to fetch dependencies from your CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. On the overview page for your project, choose **Packages**.
1. Choose your package repository from the list of package repositories.
1. Choose **Connect to repository**.
1. In the **Connect to repository** dialog box, choose **mvn** from the list of package manager clients.
1. You will need a personal access token (PAT) to authenticate `mvn` with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.
1. Choose **Create token**.
1. Choose **Copy** to copy your PAT.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box.
1. Add a profile containing your repository to your `settings.xml` file. Replace the following values.
**Note**
If copying from the console instructions, the following values should be updated for you and should not be changed.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
```
repo_name
true
repo_name
https://packages.region.codecatalyst.aws/maven/space_name/proj_name/repo_name/
```
1. Add your server to the list of servers in your `settings.xml` file. Replace the following values.
**Note**
If copying from the console instructions, the following values should be updated for you and should not be changed.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
+ Replace *username* with your CodeCatalyst user name.
+ Replace *PAT* with your CodeCatalyst PAT.
```
repo_name
username
PAT
```
1. (Optional) Set a mirror in your `settings.xml` file that captures all connections and routes them to your repository instead of a gateway repository.
**Note**
If copying from the console instructions, the following values should be updated for you and should not be changed.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
```
repo_name
repo_name
https://packages.region.codecatalyst.aws/maven/space_name/proj_name/repo_name/
*
```
**Important**
You can use any value in the `` element, but it must be the same in both the `` and `` elements. This enables the specified credentials to be included in requests to CodeCatalyst.
After you make these configuration changes, you can build the project.
```
mvn compile
```
## Fetching packages from external package repositories through CodeCatalyst
You can install Maven packages from public repositories through a CodeCatalyst repository by configuring it with an upstream connection to the gateway that represents the gateway repository. Packages installed from the gateway repository are ingested and stored in your CodeCatalyst repository.
Currently, CodeCatalyst supports the following public Maven package repositories.
+ maven-central-gateway
+ google-android-gateway
+ gradle-plugins-gateway
+ commonsware-gateway
**To install packages from public Maven package repositories**
1. If you haven't already, configure `mvn` with your CodeCatalyst package repository by following the steps in [Fetching dependencies from CodeCatalyst](#mvn-fetch-dependencies).
1. Ensure your repository has added the gateway repository you want to install from as an upstream connection. To check which upstream sources are added or to add a gateway repository as an upstream source, followthe instructions in [Adding an upstream repository](packages-upstream-repositories-add.md).
For more information about requesting packages from upstream repositories, see [Requesting a package version with upstream repositories](packages-upstream-repositories-request.md).
## Publishing packages to CodeCatalyst
To publish a Maven package with `mvn` to a CodeCatalyst repository, you must also edit `~/.m2/settings.xml` and the project POM.
**To use `mvn` to publish packages to your CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. On the overview page for your project, choose **Packages**.
1. Choose your package repository from the list of package repositories.
1. Choose **Connect to repository**.
1. In the **Connect to repository** dialog box, choose **mvn** from the list of package manager clients.
1. You will need a personal access token (PAT) to authenticate `mvn` with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.
1. Choose **Create token**.
1. Choose **Copy** to copy your PAT.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box.
1. Configure an environment variable on your local machine with your PAT. You will use this environment variable in your `setting.xml` file.
```
export CODECATALYST_ARTIFACTS_TOKEN=your_PAT
```
1. Add a `` section to `settings.xml` with a reference to the `CodeCatalyst_ARTIFACTS_TOKEN` environment variable so that Maven passes the token in HTTP requests.
```
...
repo-name
username
${env.CodeCatalyst_ARTIFACTS_TOKEN}
...
```
1. Add a `` section to your project's `pom.xml`.
```
...
repo_name
repo_name
https://packages.region.codecatalyst.aws/maven/space_name/proj_name/repo_name/
...
```
After you make these configuration changes, you can build the project and publish it to the specified repository.
```
mvn deploy
```
You can navigate to your package repository in the CodeCatalyst console to check that the package was successfully published.
## Publishing third-party packages
You can publish third-party Maven packages to a CodeCatalyst repository with `mvn deploy:deploy-file`. This can be helpful to users that want to publish packages and only have JAR files and don't have access to package source code or POM files.
The `mvn deploy:deploy-file` command will generate a POM file based on the information passed in the command line.
First, create a PAT if you do not have one.
**To create a personal access token (PAT)**
1. In the top menu bar, choose your profile badge, and then choose **My settings**.
**Tip**
You can also find your user profile by going to the members page for a project or space and choosing your name from the members list.
1. In **PAT name**, enter a descriptive name for your PAT.
1. In **Expiration date**, leave the default date or choose the calendar icon to select a custom date. The expiration date defaults to one year from the current date.
1. Choose **Create**.
You can also create this token when you choose **Clone repository** for a source repository.
1. Save the PAT secret in a secure location.
**Important**
The PAT secret only displays once. You cannot retrieve it after you close the window.
**To publish third-party Maven packages**
1. Create a `~/.m2/settings.xml` file with the following contents:
```
repo_name
username
PAT}
```
1. Run the `mvn deploy:deploy-file` command:
```
mvn deploy:deploy-file -DgroupId=commons-cli \
-DartifactId=commons-cli \
-Dversion=1.4 \
-Dfile=./commons-cli-1.4.jar \
-Dpackaging=jar \
-DrepositoryId=repo-name \
-Durl=https://packages.region.codecatalyst.aws/maven/space-name/proj-name/repo-name/
```
**Note**
The preceding example publishes `commons-cli 1.4`. Modify the groupId, artifactID, version, and file arguments to publish a different JAR.
These instructions are based on examples in the [Guide to deploying 3rd party JARs to remote repository](https://maven.apache.org/guides/mini/guide-3rd-party-jars-remote.html) from the *Apache Maven documentation*.
For more information, see these topics on the Apache Maven Project website:
+ [Setting up Multiple Repositories](https://maven.apache.org/guides/mini/guide-multiple-repositories.html)
+ [Settings Reference](https://maven.apache.org/settings.html)
+ [Distribution Management](https://maven.apache.org/pom.html#Distribution_Management)
+ [Profiles](https://maven.apache.org/pom.html#Profiles)
# Publishing packages with curl
This section shows how to use the HTTP client `curl` to publish Maven packages to a CodeCatalyst package repository. Publishing packages with `curl` can be useful if you do not have or want to install the Maven client in your environments.
**To publish a Maven package with `curl`**
1. You must store a personal access token (PAT) into an environment variable to authenticate `curl` with CodeCatalyst. If you already have one, you can use that. If not, you can create one and configure the environment variable.
1. Create a PAT by following the steps in [Grant users repository access with personal access tokens](ipa-tokens-keys.md). Copy the PAT to store it in an environment variable.
1. On your local machine's command line, configure an environment variable with your PAT.
```
export CodeCatalyst_ARTIFACTS_TOKEN=your_PAT
```
1. Use the following `curl` command to publish the JAR to a CodeCatalyst repository. Replace *username*, *space\$1name*, *proj\$1name*, and *repo\$1name* with your CodeCatalyst user name, space name, project name, and package repository name.
```
curl --request PUT https://packages.region.codecatalyst.aws/maven/space-name/proj-name/repo-name/com/mycompany/app/my-app/1.0/my-app-1.0.jar \
--user "username:CodeCatalyst_ARTIFACTS_TOKEN" --header "Content-Type: application/octet-stream" \
--data-binary @target/path/to/my-app-1.0.jar
```
1. Use the following `curl` command to publish the POM to a CodeCatalyst repository. Replace *username*, *space\$1name*, *proj\$1name*, and *repo\$1name* with your CodeCatalyst user name, space name, project name, and package repository name.
```
curl --request PUT https://packages.region.codecatalyst.aws/maven/space-name/proj-name/repo-name/com/mycompany/app/my-app/1.0/my-app-1.0.pom \
--user "username:CodeCatalyst_ARTIFACTS_TOKEN" --header "Content-Type: application/octet-stream" \
--data-binary @target/my-app-1.0.pom
```
1. At this point, the Maven package will be in your CodeCatalyst repository with a status of `Unfinished`. To be able to consume the package, it must be in the `Published` state. You can move the package from `Unfinished` to `Published` by either uploading a `maven-metadata.xml` file to your package, or changing the status in the CodeCatalyst console.
1. Option 1: Use the following `curl` command to add a `maven-metadata.xml` file to your package. Replace *username*, *space\$1name*, *proj\$1name*, and *repo\$1name* with your CodeCatalyst user name, space name, project name, and package repository name.
```
curl --request PUT https://packages.region.codecatalyst.aws/maven/space-name/proj-name/repo-name/com/mycompany/app/my-app/maven-metadata.xml \
--user "username:CodeCatalyst_ARTIFACTS_TOKEN" --header "Content-Type: application/octet-stream" \
--data-binary @target/maven-metadata.xml
```
Following is an example of the contents of a `maven-metadata.xml` file:
```
com.mycompany.app
my-app
1.0
1.0
1.0
20200731090423
```
1. Option 2: Update the package status to `Published` in the CodeCatalyst console. For information about how to update a package version's status, see [Updating a package version's status](working-with-packages-update-version-status.md).
If you only have a package's JAR file, you can publish a consumable package version to a CodeCatalyst repository using `mvn`. This can be useful if you do not have access to the package's source code or POM. See [Publishing third-party packages](packages-maven-mvn.md#publishing-third-party-packages) for details.
# Using Maven checksums and snapshots
The following sections describe how to use Maven checksums and Maven snapshots in CodeCatalyst.
## Using Maven checksums
When a Maven package is published to a CodeCatalyst package repository, the checksum associated with each *asset* or file in the package is used to validate the upload. Examples of assets are *jar*, *pom*, and *war* files. For each asset, the Maven package contains multiple checksum files that use the asset name with an additional extension, such as `md5` or `sha1`. For example, the checksum files for a file named `my-maven-package.jar` might be `my-maven-package.jar.md5` and `my-maven-package.jar.sha1`.
Every Maven package also contains a `maven-metadata.xml` file. This file must be uploaded for a publish to succeed. If a checksum mismatch is detected during the upload of any package file, the publish stops. This might prevent the `maven-metadata.xml` from being uploaded. When that happens, the status of the Maven package is set to `Unfinished`. You cannot download assets that are part of a package with this status.
Keep the following in mind in the event of a checksum mismatch when you publish a Maven package:
+ If the checksum mismatch occurs before `maven-metadata.xml` is uploaded, the status of the package is not set to `Unfinished`. The package is not visible and its assets cannot be consumed. When this happens, try one of the following, and then try to download the asset again.
+ Run the command that publishes the Maven package again. This might work if a network issue corrupted the checksum file during download. If the network issue is resolved for the retry, the checksum matches and the download is successful.
+ If republishing the Maven package doesn't work, delete the package and then republish it.
+ If the checksum mismatch occurs after `maven-metadata.xml` is uploaded, the status of the package is set to `Published`. You can consume any asset from the package, including those with checksum mismatches. When you download an asset, the checksum generated by CodeCatalyst is downloaded with it. If the downloaded file is associated with a checksum mismatch, its downloaded checksum file might not match the checksum that was uploaded when the package was published.
## Using Maven snapshots
A Maven *snapshot* is a special version of a Maven package that refers to the latest production branch code. It is a development version that precedes the final release version. You can identify a snapshot version of a Maven package by the suffix `SNAPSHOT` that is appended to the package version. For example, the snapshot of version `1.1` is `1.1-SNAPSHOT`. For more information, see [What is a SNAPSHOT version?](https://maven.apache.org/guides/getting-started/index.html#What_is_a_SNAPSHOT_version) on the Apache Maven Project website.
CodeCatalyst supports publishing and consuming Maven snapshots. You can publish a Maven snapshot to a CodeCatalyst repository or, if you are directly connected, to an upstream repository. However, a snapshot version in both a package repository and one of its upstream repositories is not supported. For example, if you upload a Maven package with version `1.2-SNAPSHOT` to your package repository, CodeCatalyst does not support uploading a Maven package with the same snapshot version to one of its upstream repositories. This scenario might return unpredictable results.
When a Maven snapshot is published, its previous version is preserved in a new version called a *build*. Each time a Maven snapshot is published, a new build version is created. All previous versions of a snapshot are maintained in its build versions. When a Maven snapshot is published, its status is set to `Published` and the status of the build that contains the previous version is set to `Unlisted`.
If you request a snapshot, the version with status `Published` is returned. This is always the most recent version of the Maven snapshot. You can also request a particular build of a snapshot.
To delete all build versions of a Maven snapshot, use the CodeCatalyst console.
# Using NuGet
These topics describe how to consume and publish `NuGet` packages using CodeCatalyst.
**Note**
CodeCatalyst supports [NuGet version 4.8](https://docs.microsoft.com/en-us/nuget/release-notes/nuget-4.8-rtm) and higher.
**Topics**
+ [Using CodeCatalyst with Visual Studio](packages-nuget-visual-studio.md)
+ [Configuring and using the nuget or dotnet CLI](packages-nuget-cli.md)
+ [NuGet package name, version, and asset name normalization](nuget-name-normalization.md)
+ [NuGet compatibility](packages-nuget-compatibility.md)
# Using CodeCatalyst with Visual Studio
You can consume packages from CodeCatalyst directly in Visual Studio.
To configure and use NuGet with CLI tools such as `dotnet` or `nuget`, see [Configuring and using the nuget or dotnet CLI](packages-nuget-cli.md).
**Contents**
+ [Configuring Visual Studio with CodeCatalyst](#packages-nuget-vs-configure)
+ [Windows](#packages-nuget-vs-configure-windows)
+ [macOS](#packages-nuget-vs-configure-mac)
## Configuring Visual Studio with CodeCatalyst
### Windows
**To configure Visual Studio with CodeCatalyst**
1. A personal access token (PAT) is required to authenticate with CodeCatalyst. If you already have one, you can use that. If not, follow the instructions in [Grant users repository access with personal access tokens](ipa-tokens-keys.md) to create one.
1. Use `nuget` or `dotnet` to configure your package repository and credentials.
------
#### [ dotnet ]
**Linux and macOS users:** Because encryption is not supported on non-Windows platforms, you must add the `--store-password-in-clear-text` flag to the following command. Note that this will store your password as plaintext in your configuration file.
```
dotnet nuget add source https://packages.region.codecatalyst.aws/nuget/space-name/proj-name/repo-name/v3/index.json --name repo_name --password PAT --username user_name
```
------
#### [ nuget ]
```
nuget sources add -name repo_name -Source https://packages.region.codecatalyst.aws/nuget/space-name/proj-name/repo-name/v3/index.json -password PAT --username user_name
```
------
Example output:
```
Package source with Name: repo_name added successfully.
```
1. Configure Visual Studio to use your new package source. In Visual Studio, choose **Tools**, and then choose **Options**.
1. In the **Options** menu, expand the **NuGet Package Manager** section and choose **Package Sources**.
1. In the **Available package sources** list, make sure that your *repo\$1name* source is enabled. If you have configured your package repository with an upstream connection to the NuGet Gallery, disable the **nuget.org** source .
### macOS
**To configure Visual Studio with CodeCatalyst**
1. A personal access token (PAT) is required to authenticate with CodeCatalyst. If you already have one, you can use that. If not, follow the instructions in [Grant users repository access with personal access tokens](ipa-tokens-keys.md) to create one.
1. Choose **Preferences** from the menu bar.
1. In the **NuGet** section, choose **Sources**.
1. Choose **Add** and add your repository information.
1. For **Name**, enter your CodeCatalyst package repository name.
1. For **Location**, enter your CodeCatalyst package repository endpoint. The following snippet shows an example endpoint. Replace *space-name*, *proj-name*, and *repo-name* with your CodeCatalyst space name, project name, and repository name.
```
https://packages.region.codecatalyst.aws/nuget/space-name/proj-name/repo-name/
```
1. For **Username**, enter any valid value.
1. For **Password**, enter your PAT.
1. Choose **Add source**.
1. If you have configured your package repository with an upstream connection to the NuGet Gallery, disable the **nuget.org** source.
After configuration, Visual Studio can consume packages from your CodeCatalyst repository, any of its upstream repositories, or from [NuGet.org](https://www.nuget.org/) if you have it configured as an upstream source. For more information about browsing and installing NuGet packages in Visual Studio, see [Install and manage packages in Visual Studio using the NuGet Package Manager](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-visual-studio) in the *NuGet documentation*.
# Configuring and using the nuget or dotnet CLI
You can use CLI tools such as `NuGet` and `dotnet` to publish and consume packages from CodeCatalyst. This document provides information about configuring the CLI tools and using them to publish or consume packages.
**Contents**
+ [Configuring NuGet with CodeCatalyst](#nuget-configure-cli)
+ [Consuming NuGet packages from a CodeCatalyst repository](#nuget-consume-cli)
+ [Consuming NuGet packages from NuGet.org through CodeCatalyst](#nuget-consume-nuget-gallery)
+ [Publishing NuGet packages to CodeCatalyst](#nuget-publish-cli)
## Configuring NuGet with CodeCatalyst
To configure NuGet with CodeCatalyst, add a repository endpoint and personal access token to your NuGet configuration file to allow `nuget` or `dotnet` to connect to your CodeCatalyst package repository.
**To configure NuGet with your CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. On the overview page for your project, choose **Packages**.
1. Choose your package repository from the list of package repositories.
1. Choose **Connect to repository**.
1. In the **Connect to repository** dialog box, choose **NuGet** or **dotnet** from the list of package manager clients.
1. You will need a personal access token (PAT) to authenticate NuGet with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.
1. Choose **Create token**.
1. Choose **Copy** to copy your PAT.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box.
1. Configure `nuget` or `dotnet` to use your repository's NuGet endpoint and CodeCatalyst PAT. Replace the following values.
**Note**
If copying from the console instructions, the following values should be updated for you and should not be changed.
+ Replace *username* with your CodeCatalyst user name.
+ Replace *PAT* with your CodeCatalyst PAT.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
1. For `nuget`, use the `nuget sources add` command.
```
nuget sources add -name "repo_name" -Source "https://packages.region.codecatalyst.aws/nuget/space_name/proj_name/repo_name/v3/index.json" -username "username" -password "PAT"
```
1. For `dotnet`, use the `dotnet nuget add source` command.
**Linux and macOS users**: Because encryption is not supported on non-Windows platforms, you must add the `--store-password-in-clear-text` flag to the following command. Note that this will store your password as plaintext in your configuration file.
```
dotnet nuget add source "https://packages.region.codecatalyst.aws/nuget/space_name/proj_name/repo_name/v3/index.json" -n "proj_name/repo_name" -u "username" -p "PAT" --store-password-in-clear-text
```
Once you have configured NuGet with CodeCatalyst, you can [consume NuGet packages](#nuget-consume-cli) that are stored in your CodeCatalyst repository or one of its upstream repositories and [publish NuGet packages](#nuget-publish-cli) to your CodeCatalyst repository.
## Consuming NuGet packages from a CodeCatalyst repository
Once you have [configured NuGet with CodeCatalyst](#nuget-configure-cli), you can consume NuGet packages that are stored in your CodeCatalyst repository or one of its upstream repositories.
To consume a package version from a CodeCatalyst repository or one of its upstream repositories with nuget or dotnet, run the following command. Replace *packageName* with the name of the package you want to consume and *packageSourceName* with the source name for your CodeCatalyst package repository in your NuGet configuration file, which should be the repository name.
**To install a package with `dotnet`**
```
dotnet add packageName --source packageSourceName
```
**To install a package with `nuget`**
```
nuget install packageName --source packageSourceName
```
For more information, see [Manage packages using the nuget CLI](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-nuget-cli) or [Install and manage packages using the dotnet CLI](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-dotnet-cli) in the *Microsoft Documentation*.
## Consuming NuGet packages from NuGet.org through CodeCatalyst
You can consume NuGet packages from [NuGet.org](https://www.nuget.org/) through a CodeCatalyst repository by configuring the repository with an upstream connection to **NuGet.org**. Packages consumed from **NuGet.org** are ingested and stored in your CodeCatalyst repository.
**To consume packages from NuGet.org**
1. If you haven't already, configure your NuGet package manager with your CodeCatalyst package repository by following the steps in [Configuring NuGet with CodeCatalyst](#nuget-configure-cli).
1. Ensure that your repository has added **NuGet.org** as an upstream connection. You can check which upstream sources are added or add **Nuget.org** as an upstream source by following the instructions in [Adding an upstream repository](packages-upstream-repositories-add.md) and choosing the **NuGet store** repository.
## Publishing NuGet packages to CodeCatalyst
Once you have [configured NuGet with CodeCatalyst](#nuget-configure-cli), you can use `nuget` or `dotnet` to publish package versions to CodeCatalyst repositories.
To push a package version to a CodeCatalyst repository, run the following command with the full path to your `.nupkg` file and the source name for your CodeCatalyst repository in your NuGet configuration file.
**To publish a package with `dotnet`**
```
dotnet nuget push path/to/nupkg/SamplePackage.1.0.0.nupkg --source packageSourceName
```
**To publish a package with `nuget`**
```
nuget push path/to/nupkg/SamplePackage.1.0.0.nupkg --source packageSourceName
```
# NuGet package name, version, and asset name normalization
CodeCatalyst normalizes package and asset names and package versions before storing them, which means the names or versions in CodeCatalyst may be different than the ones provided when the package or asset was published.
**Package name normalization: ** CodeCatalyst normalizes NuGet package names by converting all letters to lowercase.
**Package version normalization: ** CodeCatalyst normalizes NuGet package versions using the same pattern as NuGet. The following information is from [Normalized version numbers](https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#normalized-version-numbers) from the NuGet documentation.
+ Leading zeroes are removed from version numbers:
+ `1.00` is treated as `1.0`
+ `1.01.1` is treated as `1.1.1`
+ `1.00.0.1` is treated as `1.0.0.1`
+ A zero in the fourth part of the version number will be omitted:
+ `1.0.0.0` is treated as `1.0.0`
+ `1.0.01.0` is treated as `1.0.1`
+ SemVer 2.0.0 build metadata is removed:
+ `1.0.7+r3456` is treated as `1.0.7`
**Package asset name normalization: ** CodeCatalyst constructs the NuGet package asset name from the normalized package name and package version.
# NuGet compatibility
This guide contains information about CodeCatalyst's compatibility with different NuGet tools and versions.
**Topics**
+ [General NuGet compatibility](#nuget-version-support)
+ [NuGet command line support](#nuget-command-line-support)
## General NuGet compatibility
CodeCatalyst supports NuGet 4.8 and higher.
CodeCatalyst only supports V3 of the NuGet HTTP protocol. This means that some CLI commands that rely V2 of the protocol are not supported. See the following [nuget command support](#nuget-command-support) section for more information.
CodeCatalyst does not support PowerShellGet 2.x.
## NuGet command line support
CodeCatalyst supports the NuGet (`nuget`) and .NET Core (`dotnet`) CLI tools.
### nuget command support
Because CodeCatalyst only supports V3 of NuGet's HTTP protocol, the following commands will not work when used against CodeCatalyst resources:
+ `list`: The `nuget list` command displays a list of packages from a given source. To get a list of packages in a CodeCatalyst package repository, navigate to the repository in the CodeCatalyst console.
# Using Python
These topics describe how to use `pip`, the Python package manager, and `twine`, the Python package publishing utility, with CodeCatalyst.
**Topics**
+ [Configuring pip and installing Python packages](packages-python-pip.md)
+ [Configuring Twine and publishing Python packages](packages-python-twine.md)
+ [Python package name normalization](python-name-normalization.md)
+ [Python compatibility](packages-python-compatibility.md)
# Configuring pip and installing Python packages
To use `pip` with CodeCatalyst, you must connect `pip` to your package repository and provide a personal access token for authentication. You can view instructions for connecting `pip` to your package repository in the CodeCatalyst console. After you authenticate and connect `pip` to CodeCatalyst, you can run `pip` commands.
**Contents**
+ [Installing Python packages from CodeCatalyst with pip](#pip-install)
+ [Consuming Python packages from PyPI through CodeCatalyst](#pip-install-pypi)
+ [pip command support](#pip-command-support)
+ [Supported commands that interact with a repository](#supported-pip-commands-that-interact-with-a-repository)
+ [Supported client-side commands](#supported-pip-client-side-commands)
## Installing Python packages from CodeCatalyst with pip
The following instructions explain how to configure `pip` to install Python packages from your CodeCatalyst package repository or one of its upstream repositories.
**To configure and use `pip` to install Python packages from your CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. On the overview page for your project, choose **Packages**.
1. Choose your package repository from the list of package repositories.
1. Choose **Connect to repository**.
1. In the **Connect to repository** dialog box, choose **pip** from the list of package manager clients.
1. You will need a personal access token (PAT) to authenticate pip with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.
1. Choose **Create token**.
1. Choose **Copy** to copy your PAT.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box.
1. Use the `pip config` command to set the CodeCatalyst registry URL and credentials. Replace the following values.
**Note**
If copying from the console instructions, the following values should be updated for you and should not be changed.
+ Replace *username* with your CodeCatalyst user name.
+ Replace *PAT* with your CodeCatalyst PAT.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
```
pip config set global.index-url https://username:PAT@https://packages.region.codecatalyst.aws/pypi/space_name/proj_name/repo_name/simple/
```
1. Assuming that a package is present in your repository or one of its upstream repositories, you can install it with `pip install`. For example, use the following command to install the `requests` package.
```
pip install requests
```
Use the `-i` option to revert temporarily to installing packages from [https://pypi.org](https://pypi.org) instead of your CodeCatalyst package repository.
```
pip install -i https://pypi.org/simple requests
```
## Consuming Python packages from PyPI through CodeCatalyst
You can consume Python packages from the [Python Package Index (PyPI)](https://www.pypi.org/) through a CodeCatalyst repository by configuring the repository with an upstream connection to **PyPI**. Packages consumed from **PyPI** are ingested and stored in your CodeCatalyst repository.
**To consume packages from PyPI**
1. If you haven't already, configure pip with your CodeCatalyst package repository by following the steps in [Installing Python packages from CodeCatalyst with pip](#pip-install).
1. Ensure that your repository has added **PyPI** as an upstream source. You can check which upstream sources are added or add **PyPI** as an upstream source by following the instructions in [Adding an upstream repository](packages-upstream-repositories-add.md) and choosing the **PyPI store** repository.
For more information about requesting packages from upstream repositories, see [Requesting a package version with upstream repositories](packages-upstream-repositories-request.md).
## pip command support
The following sections summarize the pip commands that are supported, by CodeCatalyst repositories, in addition to specific commands that are not supported.
**Topics**
+ [Supported commands that interact with a repository](#supported-pip-commands-that-interact-with-a-repository)
+ [Supported client-side commands](#supported-pip-client-side-commands)
### Supported commands that interact with a repository
This section lists `pip` commands where the `pip` client makes one or more requests to the registry it's been configured with. These commands have been verified to function correctly when invoked against a CodeCatalyst package repository.
****
| Command | Description |
| --- | --- |
| [install](https://pip.pypa.io/en/stable/reference/pip_install/) | Install packages. |
| [download](https://pip.pypa.io/en/stable/reference/pip_download/) | Download packages. |
CodeCatalyst does not implement `pip search`. If you have configured `pip` with a CodeCatalyst package repository, running `pip search` will search and show packages from [PyPI](https://pypi.org/).
### Supported client-side commands
These commands don't require any direct interaction with a repository, so CodeCatalyst does not need to do anything to support them.
****
| Command | Description |
| --- | --- |
| [uninstall](https://pip.pypa.io/en/stable/reference/pip_uninstall/) | Uninstall packages. |
| [freeze](https://pip.pypa.io/en/stable/reference/pip_freeze/) | Output installed packages in requirements format. |
| [list](https://pip.pypa.io/en/stable/reference/pip_list/) | List installed packages. |
| [show](https://pip.pypa.io/en/stable/reference/pip_show/) | Show information about installed packages. |
| [check](https://pip.pypa.io/en/stable/reference/pip_check/) | Verify that installed packages have compatible dependencies. |
| [config](https://pip.pypa.io/en/stable/reference/pip_config/) | Manage local and global configuration. |
| [wheel](https://pip.pypa.io/en/stable/reference/pip_wheel/) | Build wheels from your requirements. |
| [hash](https://pip.pypa.io/en/stable/reference/pip_hash/) | Compute hashes of package archives. |
| [completion](https://pip.pypa.io/en/stable/user_guide/#command-completion) | Helps with command completion. |
| [debug](https://pip.pypa.io/en/stable/reference/pip_debug/) | Show information useful for debugging. |
| help | Show help for commands. |
# Configuring Twine and publishing Python packages
To use `twine` with CodeCatalyst, you must connect `twine` to your package repository and provide a personal access token for authentication. You can view instructions for connecting `twine` to your package repository in the CodeCatalyst console. After you authenticate and connect `twine` to CodeCatalyst, you can run `twine` commands.
## Publishing packages to CodeCatalyst with Twine
The following instructions explain how to authenticate and connect `twine` to your CodeCatalyst package repository.
**To configure and use `twine` to publish packages to your CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. On the overview page for your project, choose **Packages**.
1. Choose your package repository from the list of package repositories.
1. Choose **Connect to repository**.
1. In the **Connect to repository** dialog box, choose **Twine** from the list of package manager clients.
1. You will need a personal access token (PAT) to authenticate twine with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.
1. Choose **Create token**.
1. Choose **Copy** to copy your PAT.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box.
1. You can configure twine with a `.pypirc` file, or with environment variables.
1. **To configure with a `.pypirc` file.**
Open `~/.pypirc` in your editor of choice.
Add an index server for CodeCatalyst, including the repository, user name, and PAT that you created and copied in a previous step. Replace the following values.
**Note**
If copying from the console instructions, the following values should be updated for you and should not be changed.
+ Replace *username* with your CodeCatalyst user name.
+ Replace *PAT* with your CodeCatalyst PAT.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
```
[distutils]
index-servers = proj-name/repo-name
[proj-name/repo-name]
repository = https://packages.region.codecatalyst.aws/pypi/space_name/proj_name/repo_name/
password = PAT
username = username
```
1. **To configure with environment variables.**
Set the following environment variables. In the `TWINE_REPOSITORY_URL` value, update *space\$1name*, *proj\$1name*, and *repo\$1name* with your CodeCatalyst space, project, and package repository names.
```
export TWINE_USERNAME=username
```
```
export TWINE_PASSWORD=PAT
```
```
export TWINE_REPOSITORY_URL="https://packages.region.codecatalyst.aws/pypi/space_name/proj_name/repo_name/"
```
1. Publish a Python distribution with the `twine upload` command.
# Python package name normalization
CodeCatalyst normalizes package names before storing them, which means the package names in CodeCatalyst may be different than the name provided when the package was published.
For Python packages, when performing normalization the package name is lowercased and all instances of the characters `.`, `-`, and `_` are replaced with a single `-` character. So the package names `pigeon_cli` and `pigeon.cli` are normalized and stored as `pigeon-cli`. The non-normalized name can be used by pip and twine. For more information about Python package name normalization, see [PEP 503](https://www.python.org/dev/peps/pep-0503/#normalized-names) in the Python documentation.
# Python compatibility
While CodeCatalyst does not support the `/simple/` API, it does support the `Legacy` API operations. CodeCatalyst does not support PyPI's `XML-RPC` or `JSON` API operations.
For more information, see the following on the Python Packaging Authority's GitHub repository.
+ [Legacy API](https://warehouse.pypa.io/api-reference/legacy.html)
+ [XML-RPC API](https://github.com/pypi/warehouse/blob/main/docs/dev/api-reference/xml-rpc.rst)
+ [JSON API](https://docs.pypi.org/api/json/)
# Quotas for packages
The following table describes quotas and limits for packages in Amazon CodeCatalyst. For more information about quotas in Amazon CodeCatalyst, see [Quotas for CodeCatalyst](quotas.md).
| Resource | Default quota |
| --- | --- |
| Package repositories | Maximum of 1000 per space. |
| Direct upstream repositories | Maximum of 10 per package repository. |
| Upstream package repositories searched | Maximum of 25 upstream repositories searched per requested package version. |
| Package asset file size | Maximum of 5GB per package asset. |
| Package assets | Maximum of 150 per package version. |