Prerelease Packages & Repackaging

ProGet's repackacing feature simplifies your package-based CI/CD pipelines by creating stable, production-ready packages from tested and verified prerelease packages. These "repackaged" packages have identical contents, and ProGet maintains an audit trail within the package to trace back to original versions, who performed the operation, and when.

How/When Should I Repackage?

This is a relatively complex topic, and a good starting point is our guide on How to Create CI/CD pipelines for your NuGet packages.

Essentially, repackaging is performed as a package "advances" from one CI/CD pipeline stage to another. Repackaging leverages Semantic Versioning's Prerelease Labels to effectively "change" a package version from unstable (e.g. 1.0.0-ci.8) to less-unstable (e.g. 1.0.0-rc.8), and eventually to a stable version (e.g. 1.0.0).

This package-based CI/CD pipeline allows you to test the exact same content in each stage without rebuilding packages that may have different content. It also helps ensure that prerelease packages are never released, and developers aren't confused by hundreds of different package versions.

While this a CI/CD pipeline will necessarily create lots and lots of prerelease packages, you can use ProGet's Retention Rules to automatically clean those up.

How To Repackage a Package

Repackaging is available for Universal and NuGet packages, and is generally done as part of a CI/CD process using the Repackaging API. You can also repackage using the ProGet web interface.

Repackaging in the Web UI

1. Go to the "Package Overview" page for any Universal or NuGet package in ProGet.
2. Select "Repackage" from the dropdown.
3. Enter a new version number. You may also optionally add a reason (for auditing purposes).
   • Selecting the same feed from the dropdown just repackages the package, leaving it in the same feed.
   • Selecting a different feed from the dropdown promotes the repackaged package to the target feed (the repackaged version will not show up in the source feed).
4. Click "Repackage."

Viewing and Auditing Repackage History

ProGet allows users to see the repackaging audit trail on the "History" tab of the package. The history will show key values regarding each repackaging event such as the date, time, version, username, notes, and more.

These historic audit trails are embedded within the package itself and allows you to easily replicate or promote this package to other feeds while preserving the repackaging history. For Universal packages, the history is embedded in upack.json. For NuGet packages, the history is embedded (in the same JSON format) in .progetRepackagingHistory.json in the .nupkg file.

Other Repackaging Options

ProGet's Web UI and Repackacing API make repackaging easy, but they're not the only options

Repackaging & Promoting

You can also repackage and promote in one step by selecting a different target feed from the dropdown (in the UI), or when using the API.

Repackacing by Hand

A package is really just a zip file, which means you can manually repackage with a few simple steps:

1. downloading the package file
2. opening the package file as a zip file
3. editing the package manifest file and changing the version number
4. publishing the edited package file

When ProGet performs these steps, it adds also adds an audit trail that is displayed on the package History tab in the Web Interface.

• Universal Package Manifests use the built-in repackageHistory property
• NuGet packages have a .progetRepackageHistory.json file added to the root that's uses the same format as repackageHistory

Using the upack CLI

The repack command in the Universal Package CLI (upack) can be used to repackage a package file, and offers the most flexibility.

Basic Repackaging (Changing Version Number)

PS C:\tmp\accounts> upack repack Accounts-1.0.0-ci.8.upack --version=1.0.0

Advanced Repackaging (Custom Manifest)

You may wish to change custom metadata as you repackage. For example, if you wanted to rewrite the description of a package and add a _serviceNowTicketId that tracks back to some internal ticketing system, you could do so as follows:

First, create a file called updated.json contents:

{
  "description": "This is a new description and will overwrite the package's existing description",
  "_serviceNowTicketId": "1000"
}

Then, run the repack command:

PS C:\tmp\accounts> upack repack Accounts-1.0.0.upack --manifest=updated.json --overwrite

Repackaging In Action

We use our public BuildMaster instance for our CI/CD Pipelines, and our public ProGet instance to host our .NET Libraries (NuGet packages) and products (Universal Packages).

You can find lots of examples on our public instances, but the Inedo.ServiceMessaging is a good start. It's a library that's used by all of our products.

The Inedo.ServiceMessaging versions page will show you the most recent versions of this package, and will include pre-releases. If you navigate to a specific version, such as Inedo.ServiceMessaging-1.1.1), you can see:

• Repackacing from -ci.3 and -rc3 on the History tab
• .progetRepackageHistory.json on the Files tab

The corresponding Inedo.ServiceMessaging build in BuildMaster will show:

• CI/CD Pipeline from Build to Release
• Scripts used to repackage