In a previous back-to-basics blog post we covered manually creating Chocolatey packages. In this post we'll take your package creation skills to the next level by automating the update process.
A Quick Refresher
It's always good to keep in mind what a Chocolatey package is, so we'll start with a quick refresher. For a deeper dive please refer back to our first back-to-basics blog post.
First, it's important to remember that a package is not software. Instead, a package is a "container" that contains something that needs to be enacted on or delivered to a computer. This could include a software installer that needs to be executed, a font to be installed, or a file that needs to be stored in a specific directory. The possibilities are endless.
Another feature of a package is metadata about what is contained inside of it. This includes a unique identifier for the package, and a version number allowing you to update or rollback the package to a known point in time.
What Is Automatic Packaging?
Automatic packaging, as you might expect, automatically updates a Chocolatey package to reflect and update to its contents. This is most often done with packages that contain software installers as there is a very obvious link between a new version of the software and the need for a new version of its package.
In order to set up automatic packaging of a package that contains/manages a software installer, you will need:
- Some way of detecting that an update is required.
- Collection of metadata including the new version number and the new installer download location.
- The ability to update the files in your package, specifically the
.nuspec
file and any PowerShell scripts.
The first two items are generally closely coupled, as you're likely to get your metadata from the same place as you're looking to tell if there is an update available. This could be the download page on a given piece of software's official webpage, release notes RSS feed, or the releases or tags listed on a GitHub repository.
To actually carry out the update of the files in your package, you could create your own script. However, a lot of the hard work has already been done for you via the Chocolatey-AU PowerShell Module (also available as a Chocolatey package). Originally created by Miodrag Milić, it has recently been adopted by the Chocolatey Community and contains functions that enable easy automatic packaging.
How Do You Automate Package Updates?
When we covered manual packaging, we created a package for Elk Native. You can find the result of this work on GitHub.
We will continue by taking the elk-native
package from manual to automatic.
Get Your Metadata
As mentioned above, we need to both determine that an update is available and also collect metadata about the update. Elk Native is open source and is released via the project's GitHub repository, meaning that we can get the information we need from the GitHub API.
The generic form of the API endpoint we're using is: https://api.github.com/repos/<org>/<project>/releases/latest
To query this API, specifically for the Elk Native software, using PowerShell we can run:
$LatestRelease = Invoke-RestMethod -UseBasicParsing -Uri "https://api.github.com/repos/elk-zone/elk-native/releases/latest"
This command stores the response from GitHub in a variable called $LatestRelease
so that we can pull information from it without needing to request the information from GitHub multiple times. You'll also notice the use of the -UseBasicParsing
parameter. This is included simply because I will be executing this script via GitHub Actions and this parameter tells PowerShell not to attempt to use the Internet Explorer engine to parse the API response, as it won't be available.
:choco-info: NOTE
In this example we are not providing any form of authentication to the GitHub API. This means that we are restricted to 60 requests per hour. Given this, you should consider authenticating to the API which increases the applicable rate limit to 5,000 requests per hour.
From this release information we need to get the version number, the download URL, and a link to the release notes. Your package may need more or less information that this, read through your .nuspec
file and ensure you're aware of everything that needs to be updated from version to version.
# Version Number
$Version = $LatestRelease.tag_name.Replace('elk-native-v', '')
# Download URL
$URL64 = ($LatestRelease.assets | Where-Object {$_.name.EndsWith("_windows_x86_64.msi")}).browser_download_url
# Release Notes URL
$ReleaseNotes = $LatestRelease.html_url
Here you'll see that we are referencing the "tag name" from the GitHub release to determine the version number. Often, you'll find that the version number is prefixed with a "v" that needs to be trimmed so that you just have "the version number" itself, but in the case of Elk Native, there is much more text that needs to be removed.
For the download URL, there is often a large number of "assets" attached to a GitHub release. These are for different Operating Systems, such as Windows, Linux, and macOS. They're also for different processor architectures, like x64, x86, or even ARM. Your package may require multiple installers, but the Elk Native installer only comes in a 64-bit variant and so we're only getting a single installer.
We now have our metadata, but how do we know that there's actually an update available? In short, you compare the version number we've collected in this step to the version number in our .nuspec
file. You could write a script to make this comparison, or we can lean on the Chocolatey-AU module to do this for us.
Put Chocolatey-AU to Work
Now that we know how to get out metadata, we can start working on our actual Chocolatey-AU update script. We'll start the script by explicitly importing the module:
Import-Module Chocolatey-AU
Following this we'll populate a specially named function called au_GetLatest
that is executed to gather metadata. We've largely already done this, however instead of saving the values into variables, we'll instead build and return a hash table. The data in this hash table will be assigned to an automatic variable called $Latest
by the Chocolatey-AU module.
function global:au_GetLatest {
$LatestRelease = Invoke-RestMethod -UseBasicParsing -Uri "https://api.github.com/repos/elk-zone/elk-native/releases/latest"
@{
URL64 = ($LatestRelease.assets | Where-Object {$_.name.EndsWith("_windows_x86_64.msi")}).browser_download_url
Version = $LatestRelease.tag_name.Replace('elk-native-v', '')
ReleaseNotes = $LatestRelease.html_url
}
}
Next we'll define a second specially named function called au_SearchReplace
. This function is executed to update the files in your package. The content of this function is a hash table of paths to files, with a nested hash table per file that specifies a RegEx to search for inside said file and what to replace the matching content with.
function global:au_SearchReplace {
@{
".\tools\chocolateyInstall.ps1" = @{
"(?i)(^\s*(\$)url64\s*=\s*)('.*')" = "`$1'$($Latest.URL64)'"
"(?i)(^\s*checksum64\s*=\s*)('.*')" = "`$1'$($Latest.Checksum64)'"
"(?i)(^\s*checksumType64\s*=\s*)('.*')" = "`$1'$($Latest.ChecksumType64)'"
}
"elk-native.nuspec" = @{
"(\<releaseNotes\>).*?(\</releaseNotes\>)" = "`$1$($Latest.ReleaseNotes)`$2"
}
}
}
In this example, you'll see that we're updating both the chocolateyInstall.ps1
and elk-native.nuspec
files. You may find yourself asking two questions, however?
- Why haven't we specified a Search and Replace pair for the Version number? This is because Chocolatey-AU does this for us automatically, and so we don't need to worry about it.
- Where did those
Checksum64
andChecksumType64
properties come from? Chocolatey-AU automatically downloads the installer and calculates the checksum for us, then adds these values to the$Latest
variable alongside the properties we gathered in theau_GetLatest
function.
The final step is to actually execute the update. By default, Chocolatey-AU will assume that there is a 32-bit installed included in the package and so the Elk Native update will error because it only has a 64-bit installer. We avoid this error, but specifying what we need a checksum calculated for.
update -ChecksumFor 64
Save this script as update.ps1
into the root of the directory containing your package. It should be alongside your package's .nuspec
file.
Updating the Package
Now we can run our update script and generate an updated package:
.\update.ps1
If any update is available, you should see a number of things happen. You will have an updated .nuspec
file as well as any PowerShell scripts that required updating, and your package will be packed into the Chocolatey package file (.nupkg
). This can then be pushed to the Chocolatey Community Repository, if it's a community package, or your own internal repository.
If an update isn't available, Chocolatey-AU will tell you so and won't create a new package.
In some cases you may need to force an update to your package, for example if the developer of the software has changed the installer without releasing a new version of the software, then the checksum in the original package will no longer match. You can force an update by setting the $au_Force
variable to $true
and then running your update script.
$au_Force = $true; .\update.ps1
The result will be your package updated with a version number that uses package fix version notation.
Next Steps
You now have a script you can run to generate an updated package. From here you can either set your API key in the $ENV:api_key
environment variable and have Chocolatey-AU push the updated package to the Chocolatey Community Repository, or use the choco push
command to push the package after Chocolatey-AU has completed.
You can also run your update script on a schedule to automate the update process. You could do this via a Scheduled Job on your computer, or use a service like GitHub Actions.
GitHub Actions is how I have personally automated the packages that I maintain, and while setting this up is beyond the scope of this blog post you can inspect the configuration for this here.
Common Questions
I covered one example of automating package updates in this post, but there are a few common questions that will be raised as you have been reading.
Are There Other Chocolatey-AU Functions?
The update script in this post only used two Chocolatey-AU functions to define how to update our package: au_GetLatest
and au_SearchReplace
. But there are two other useful functions:
au_BeforeUpdate
can be used to perform actions like manually generating the checksum for files when the automatic checksum is not suitable. It can also be used to download files that you wish to embed in your package rather than just specifying a download URL.au_AfterUpdate
can be used to execute commands after the package update has completed, but before the package is packed. You can use this for manipulating files above and beyond what is possible with a RegEx search and replace.
Are There Good Examples of Chocolatey-AU Usage?
The biggest source of examples is the Chocolatey Community Chocolatey Packages repository. This is a repository maintained by the Chocolatey Community, rather than any one individual and hosts many automatically updated packages ranging from simple to much more complex packages.
When I was learning, I took a lot of inspiration from Maurice Kevenaar's Chocolatey Packages repository.
I Have More Questions!
Check the Chocolatey Packaging FAQ, leave a comment below, or reach out for community assistance on our Community Hub.
Wrap Up
This is the fifth post in our back-to-basics series. We do hope you've found this series interesting and helpful. We look forward to continuing to expand the series. Please do let us know if there are specific topics you would like to see covered!
If you have any more questions, please reach out for community assistance on our Community Hub.
Popular Tags
- #news 68 Number of post with tag news
- #press release 55 Number of post with tag press release
- #chocolatey for business 44 Number of post with tag chocolatey for business
- #packaging 21 Number of post with tag packaging
- #open source 16 Number of post with tag open source
- #community 14 Number of post with tag community
- #tutorial 14 Number of post with tag tutorial
- #12 days of Chocolatey 2023 12 Number of post with tag 12 days of Chocolatey 2023
- #chocolatey community repository 12 Number of post with tag chocolatey community repository
- #podcast 11 Number of post with tag podcast