What Is The Chocolatey Community Repository?

In our first back-to-basics blog post, we wanted to go back to one of the first things that people find out about Chocolatey: the Chocolatey Community Repository. What is the Chocolatey Community Repository, how do you use it, and how does it work?

A Little History

Not long after Chocolatey CLI was first released in March 2011, the Chocolatey Community Repository was born, in September 2011. In the early days the repository was a place to store packages for installation with Chocolatey CLI. Moderation of packages didn't start until October 2014. Things were a little simpler back then, both for the Chocolatey Community Repository and the internet as a whole.

What Is The Chocolatey Community Repository?

In simple terms the Chocolatey Community Repository is a website that allows Chocolatey products to manage packages on a computer. It stores those packages and allows them to be consumed by you, and others.

In more complex terms, the Chocolatey Community Repository is a NuGet v2 endpoint (soon to be NuGet v3) that allows Chocolatey products to query, and therefore manage packages on your computer. Chocolatey products query the endpoint for packages that you have chosen to, amongst other things, install or upgrade. The packages are then downloaded and installed.

The Chocolatey Community Repository provides a user interface for you to search, view and manually download packages too. It shows you the package, all versions of the package, the files contained within the package, virus scan results and more.

What Is A Package?

So we have the Chocolatey Community Repository. We have packages in that repository for use by the Chocolatey community. But what actually is a package?

While this blog post isn't going to dig into the technical aspects of a package (we'll do that in a later blog post), Dictionary.com has a good definition:

1. a bundle of something, usually of small or medium size, that is packed and wrapped or boxed; parcel.
2. a container, as a box or case, in which something is or may be packed.

That definition is more akin to a package you'd have delivered. But it is a good definition of a Chocolatey package too: it's simply a container, in this case a Zip archive, that holds:

• Contents: this could be software files, a software installer (MSI, or EXE for example), registry keys, license keys or just a binary file.
• Instructions: what to do with the contents. These instructions are written in PowerShell. So you could run the software installer, copy files to a specific folder, import registry keys or copy a license key to a specific location and then run a program to import the license keys. If you can do it in PowerShell, you can almost always do it in a Chocolatey package.

We have documentation on creating packages, and on our Chocolatey products and packages that may help.

Who Creates and Maintains Packages?

You. Me. People like us. Members of the Chocolatey Community. Anybody can create and maintain a package.

A package maintainer ensures that a package is up-to-date, works as it should and commits to continue that maintenance. There is process for packages that are out of date or no longer being maintained.

How Do You Use The Chocolatey Community Repository?

So now we have a brief understanding of what a package is, let's talk about how you can use the Chocolatey Community Repository with those packages. You can:

• Consume packages: Install, upgrade and get details on packages.
• Submit packages: Create your own packages and share them with the Chocolatey community by uploading, or as we call it, pushing them to the Chocolatey Community Repository.

Install, Upgrade and Download Packages

Before you can use packages from the Chocolatey Community Repository, make sure you have Chocolatey CLI installed. Once you have it installed, you can:

• Install packages: the majority of packages on the Chocolatey Community Repository are for common software. For example, to install Firefox, use the command choco install firefox. This command tells Chocolatey CLI to download the latest version of the firefox package from the Chocolatey Community Repository, extract the package contents, and runs the PowerShell script containing the installation instructions (the chocolateyInstall.ps1 script is used for installation). Firefox will then be installed to its default location where you can use it as normal. All of this without any interaction.
• Upgrade packages: if you have an older version of Firefox installed, and you want to upgrade to the latest one, run choco upgrade firefox. The firefox package will be downloaded, the PowerShell script will be run and Firefox will be upgraded to the latest available version. If you want to upgrade all installed packages, you can do that using choco upgrade all. Again, all of this without any interaction.

Create and Share Created Packages

If you have created a package that you feel would benefit the Chocolatey community, then the Chocolatey Community Repository is the place to share it!

We won't dive into the technical aspects here. But keeping with the spirit of back-to-basics, the most common package runs a software installer EXE, and it's easy to create one. We also have documentation for advanced uses too, such as using an MSI installer or a Zip archive.

Once you have your package created, sign in or register for an account on the Chocolatey Community Repository. Log in, go to your account, and click Show API Key to retrieve your API Key. Keep it safe as you need it when you submit packages.

Now you have everything to submit the package to the Chocolatey Community Repository using Chocolatey CLI. If you had created a package called acme-awesome-tool then use the command choco push acme-awesome-tool --source https://push.chocolatey.org --api-key <YOUR API KEY> where <YOUR API KEY> is what you retrieved earlier.

Now ... wait for the email to confirm the package has been pushed. And then wait for your package to work its way through the moderation process.

Moderation Process? What is that?

Below is a simple workflow of what happens when you submit a package to the Chocolatey Community Repository.

Results of the Package Validator, Package Verifier, Package Scanner and Human Approval steps are emailed to you. If the package fails a step, it does not proceed to the next one. You have up to 35 days to fix the issues and submit the package again. The package will then go through the package moderation process from the start. If you have any questions or issues with the process, you can leave a moderation comment on the package page and a human Moderator will pick it up and respond. The queue of packages in the moderation process can be found on the packages package.

Moderators are long-time members of the Chocolatey Community who have demonstrated maintaining packages to a high standard over a long period of time. They have experience both in how the Chocolatey Community Repository works, and what a good and useful package looks like.

Step 1: Push Package

The very first step in the package moderation process is for you to push the package to the Chocolatey Community Repository! As mentioned above, once you have created your acme-awesome-tool package, use Chocolatey CLI to do the work by using the command choco push acme-awesome-tool --source https://push.chocolatey.org --api-key <YOUR API KEY> where <YOUR API KEY> is what you retrieved from your Chocolatey Community Repository account.

Step 2: Chocolatey Community Repository Received Package

After you push the package, the Chocolatey Community Repository will acknowledge your package being received by emailing you. Each step in the moderation process is acknowledged by an email so look out for them and make sure they don't end up in your spam folder.

Step 3: Package Validator

Package Validator is a service that validates your package against rules and guidelines that have been defined. These are used to ensure the quality of packages in the Chocolatey Community Repository continue to meet the standards that the Chocolatey community expects from packages. A few of those validations are:

• The package description is missing or empty, is less than 30 characters, or more than 4000 characters.
• Private variables being used in the package PowerShell scripts.
• Package title missing.
• Missing or invalid URL's in the package metadata.

A full list of requirements, guidelines, suggestions and notes is documented.

Step 4. Package Verifier

Package Verifier is a service that installs and uninstalls your package in a sandbox environment to ensure it works as expected. As of today, this sandbox environment is Windows Server 2019, but we will be adding more operating systems in the future.

Step 5. Package Scanner

Package Scanner is a service that gathers the files that the package installs and submits them to VirusTotal which " inspects items with over 70 antivirus scanners and URL/domain blocklisting services, in addition to a myriad of tools to extract signals from the studied content". The package itself, is also submitted to VirusTotal. Once the results are known, they are added to the package page.

Step 6. Human Moderator and Trusted Package

If your package is trusted, then it will skip human moderation and move straight to the next step when it has passed all other Package Moderation steps.

Otherwise, your package will wait for a human Moderator to pick up the package and look at it. A Moderator will look at different aspects of the package to ensure that it meets the quality standards required by the Chocolatey Community Repository. They will then provide advice and help on any issues with the package through moderation comments on the package page, or move it to the next step.

Step 7. Package Approved and Available For Use

Once your package has passed all Package Moderation steps, it will be approved and be available for use. If it is the latest version, you can install it with choco install acme-awesome-tool, or upgarde to it using choco upgrade acme-awesome-tool. If not, you can install that specific version using choco install acme-awesome-tool --version <VERSION> where <VERSION> is the version you want to install.

Got Questions?

Now that you know what the Chocolatey Community Repository is, how it works and how you can use it, we know you'll have more questions.

Do I Have To Use the Chocolatey Community Repository To Host Packages?

Simple answer is no. If you're an organization, we recommend you do not use the Chocolatey Community Repository directly. Organizations have different needs to our community users, and we must ensure that the repository continues to be available for everybody and not overwhelmed.

You can create and push packages to your own internal package repository. You will have to maintain the standards of those packages yourself as Package Validator, Package Verifier and Package Scanner will not be available to you.

Can I Use The Chocolatey Community Repository For My Packages?

Packages on the Chocolatey Community Repository should have broad appeal for the Chocolatey community. Packages that have a narrow use for you, your group, organization or club should be hosted on your own repository. Similarly, the Chocolatey Community Repository is not a testing ground for you to test packages in - this is very much frowned upon!

But if your package has a broad appeal for the community, we would welcome it. See our documentation for creating packages.

I Have More Questions!

Check the Chocolatey Community Repository FAQ or reach out for community assistance on our Community Hub Discord Server.

Summary

This is the first in our back-to-basics series. The Chocolatey Community Repository is at the heart of the Chocolatey community and is typically the first exposure people have to Chocolatey packages. I hope this post helps explain what it is, how you can use it and how it works in more detail.

If you have any more questions, please reach out for community assistance on our Community Hub Discord Server.