- 27 May 2022
- 4 Minutes to read
-
Print
-
DarkLight
-
PDF
Prerelease Packages & Repackaging
- Updated on 27 May 2022
- 4 Minutes to read
-
Print
-
DarkLight
-
PDF
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 is limited in ProGet Free. You can repackage, but only through the web interface (not through the API). Additionally, you won't be able to see who repackaged or when. On the "Package Overview" page's "History" tab, repackaging and promotion history will display as date hidden
and username hidden
in the log.
Repackaging in the Web UI
- Go to the "Package Overview" page for any Universal or NuGet package in ProGet.
- Select "Repackage" from the dropdown.
- 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).
- 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:
- downloading the package file
- opening the package file as a zip file
- editing the package manifest file and changing the version number
- 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 asrepackageHistory
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