⚠️ WARNING This is a Work in Progress. Please check back later.
Please see https://chocolatey.org/blog/announcing-deployments for now.
Central Management's Deployments functionality allows for pre-defined actions to be executed across any Chocolatey-managed computers.
Deployment actions can be defined as simple
choco commands, or as fully-fledged PowerShell scripts.
Creating a Deployment
To setup a new Deployment, you'll need to create a Deployment which defines the steps for the deployment and the computers which will run them.
In order to get started, you'll need at least the
Create Deployment and/or the
Create Advanced Deployment permissions applied to your user account in CCM.
You will also need to have at least one Group of computers already defined.
From the Central Management dashboard, select
Deploymentsfrom the left sidebar.
Select the ➕ Create New Deployment button at the top of the page.
(Optional) Give the deployment a custom name by clicking the edit icon displayed next to it and entering a new name. Press Enter to save the new name.
(Optional, Requires CCM v0.4.0+) Add a schedule by selecting the ➕ Add Schedule button.
- Enter a date and time, or click the 📆 button to pick the date and time from a calendar UI.
- (Optional) If you'd like to define a maintenance window for the deployment start time, select the Restrict schedule to a maintenance window option and enter the ending date and time for the maintenance window.
Select ➕ Add Step to add your first deployment step.
(Optional) In the
Create New Deployment Stepmodal, enter a custom name for the deployment step.
Add the deployment step action:
For Basic deployment steps, select a
Script commandfrom the list, and one or more
Package name(s) to install.
For Advanced deployment steps (requires the Create Privileged Deployment user role), click the Advanced button and then enter one or more PowerShell script commands.
(Optional) Click Show advanced options to set one or more of the following options:
Valid exit codes.
Machine contact timeout(requires CCM v0.4.0+ to edit).
Fail overall deployment if not successful. Disabling this option will allow the overall deployment to be marked as successful even if the step fails. By default, if any deployment step fails, the overall deployment is marked as Failed.
Only run other deployment steps if successful. Enabling this option will prevent subsequent deployment steps from starting if this step fails. The overall deployment will be marked as Failed, and subsequent steps will be Cancelled.
Select the Select Target Groups tab.
Add groups from the Available Groups column to the Selected Groups column by selecting them from the list and pressing the
>button. You can also select the
>>button to immediately move all groups into the Selected Groups column.
Click the 💾 Save button to save the step.
Continue to add steps until your deployment is complete.
Select 💾 Save to save the changes to the deployment.
A deployment is initially created in the
Draft state, and will remain in this state until it is moved into the
While it is in the
Draft state, it cannot be run, and scheduled deployment start times will be ignored.
Once the deployment enters the
Ready state, it's eligible to be started.
Deployments in this state can be started manually or according to a schedule.
Any further modifications to a deployment in this state will revert it back to the
Deployments that are currently in progress will be in this state.
Succeeded / Failed
Deployments that have finished running will be either the
Failed state, depending on how the run went.
Deployments that are in a completed state can also be
Archived to hide them from the main Deployments screen.
This is helpful if you'd like to reduce clutter on the main deployments screen without discarding the information the completed report contains.
You can access archived deployments from the
Reports -> Deployments page in the left sidebar of the CCM dashboard.
What versions of components do I need for Deployments to work properly?
While you might be able to get things to work with CCM v0.2.x and Chocolatey Agent v0.10.x, it's best to use the following:
- CCM components (
chocolatey-management-*all 3 packages) - v0.3.0+
- Chocolatey Agents (
chocolatey-agentpackage on all clients) - v0.11.0+
- Chocolatey Licensed Extension (
chocolatey.extensionon all clients) - v2.1.1+
What is the CCM compatibility matrix?
Central Management has specific compatibility requirements with quite a few moving parts. It is important to understand that there are some Chocolatey Agent versions that may not be able to communicate with some versions of CCM and vice versa. Please see the CCM Component Compatibility Matrix for details.
Why do I see some machines have not opted in for Deployments?
If you are on the Groups screen, you may notice that some machines show up highlighted with a coloring, and one of those colorings is an orange - the legend below it mentions "Not Opted In For Deploymens (Configuration)".
As you can see from the text, it is meant to help you figure out the issue:
The computer has not opted in or a group contains computers that have not opted in for deployments by configuration. Please ensure the computer has at least chocolatey-agent v0.10.0+ installed and the feature "useChocolateyCentralManagementDeployments" has been set to enabled on the client computer.
This is telling you that you need to ensure you set the client to allow for the the use of Deployments. As it is a security consideration, it requires an explicit opt-in on client machines. See Client Setup - Features for details on how to set it.
I have plenty of licenses, why do some machines show not opted in for deployments and also exceeds your current license count?
Once you upgrade to at least CCM v0.2.0, every machine will show that until they check in the next time. Once they check in, that will go away. So it's basically normal to see that until those machines check in again.
Can I use Chocolatey Deployments to upgrade CCM based components?
Likely you absolutely can, just keep in mind that there may be a specific ordering in how you would upgrade everything and adhere to that order. In some instances, you may need to upgrade agents first, then CCM components as once CCM is upgraded it may not be able to talk to the agents. However agents will stop being able to talk to CCM for a small period of time while you are upgrading CCM, but then things will start working again.
What is Run Actual?
You may have seen
--run-actual get attached to scripts where you are running choco commands - what is it?
This is a switch that is passed to opt out of Chocolatey Self-Service. It's typically passed by the agent service back to choco to run a command for a user. You typically would not issue this, but the agent service will, so you are likely to see it in the logs if you are looking closely.
What Happens if More Than One Deployment is "Active" at the Same Time?
This will depend a little bit on the version of Central Management you're running. Prior to v4.0.0, control of deployments was handled entirely on a per-deployment-step basis. This means that if you have an active deployment with some of the computers in it idling (waiting for a later step in the deployment to begin, essentially), these machines will pick up available deployment steps from an unrelated deployment while they're waiting.
As of v4.0.0 of Central Management, this has been fine tuned a little bit so that any computer which is acted on by a deployment will not pick up any steps from unrelated deployments until all its assigned steps in the first deployment are completed.
This can get a bit confusing, so let's consider the following scenario:
- Deployment A
- Step 1
- Computer A
- Computer B
- Step 2
- Computer B
- Step 3
- Computer A
- Step 1
- Deployment B
- Step 1
- Computer A
- Step 1
Deployment A is started first, and
Deployment B starts while
Deployment A is in either step 1 or step 2.
Deployment A reaches step 2, even though
Computer A is not currently running any deployment steps, it will not start running steps from
Deployment B because it still has a task to do in
If you are running CCM 0.3.x,
Computer A will instead pick up and run the step from
Deployment B despite
Deployment A still being in progress.
Why do My Computers or Groups Show as Ineligible for Deployments While They're Opted In?
Computers can be considered ineligible for deployments based on two criteria:
- Is the computer licensed under your Chocolatey for Business license?
- Is the computer opted in for deployments based on the Chocolatey configuration?
If either one of these two criteria is not met, that computer is considered ineligible for deployments.
Additionally, any group that contains any of the following will be considered ineligible:
- An ineligible computer
- A group containing any ineligible computers
- A group containing any ineligible groups
What Happens if a Computer / Group in a Deployment Becomes Ineligible?
For deployments that have not yet started:
- If the deployment is scheduled, it will not run until all computers/groups are eligible again.
- If the deployment is not scheduled, it cannot be started until all computers/groups are eligible again.
Once CCM has confirmed the problem computer(s)/group(s) are eligible again, the deployment can be started. If the deployment was previously scheduled and it has not passed the maintenance window time (if set), it will start at that point.
For deployments that are currently
- As soon as CCM detects the ineligible computer, it will terminate the current deployment step.
- Then, all following deployment steps will be
How Can I Run Deployments in a Semi-Connected Environment?
As of CCM v0.4.0, you are able to configure deployments to tolerate semi-connected environments. This effectively allows CCM deployments to simply wait until a machine is connected to the network before it begins a given deployment step.
To configure this, you can set the
Machine Contact Timeout value in the Advanced settings of each individual Deployment Step to
This value must be positive, or zero (which is treated as infinite).
You may want to configure this only for the first step of a deployment, or for multiple steps if you expect the target machines to be connected/disconnected over the course of the deployment.
If the deployment is scheduled with a maintenance window set, the
Machine Contact Timeoutvalue of the first deployment step is ignored. In this case, the maintenance window defines the contact timeout for the first step. The
Execution Timeoutis the maximum allowed time for the Chocolatey Agent to execute the deployment step task. Any positive value for this setting will be respected, and as with
Machine Contact Timeout, a
0value is treated as infinite. However, if the execution timeout is infinite and a computer goes offline, that deployment step will not complete until that computer checks in again. If it errors three times attempting to provide the results, it will fail it at the client and that computer will not report results, and require manual intervention. Infinite execution timeouts are not recommended for this reason — deployment steps may end up seemingly stalling for long periods of time and/or require manual intervention to cancel them.
Catch the recording of the Jun 32rd, 2020 webinar for a full showcase of the Chocolatey Central Management Deployments features:
Common Errors and Resolutions
A deployment step is stalled with infinite execution timeout
The only way to resolve this currently is to cancel the deployment itself, which can be done from the main Deployments list.
On the right-hand side of the Active Deployments table, click the Actions menu for the corresponding deployment, and select
You will be asked to confirm the cancellation.
All remaining steps in the deployment will be cancelled, along with any still running or pending tasks.
The updated license file is not being picked up in the website
You need to restart the web executable currently. We are looking to have it automatically picked up in future releases. Here's a script to handle that:
Get-Service chocolatey-* | Stop-Service Get-Process ChocolateySoftware.ChocolateyManagement.Web.Mvc | Stop-Process Get-Service chocolatey-* | Start-Service
A computer or group is not showing as available for deployments but I have plenty of available licenses
Once you upgrade to Central Management v0.3.0+, you have upgraded the Agent on the machine to v0.11.0+, and it has successfully completed a check in, then that messaging should go away. Note that clients do not get a message back that there was a failure as a security feature - you'll need to consult the Central Management Service logs. You can find that at
$env:ChocolateyInstall\logs\ccm-service.log, or if you are on a version of CCM prior to 0.2.0, the log will be located at
choco commands in a script deployment break if semicolons are used to separate the statements
When constructing a PowerShell script for a deployment, all Chocolatey commands must be placed on separate lines. It is not possible to do something like the following:
choco list --local-only -r; exit $LASTEXITCODE
Instead, this should be written as:
choco list --local-only -r exit $LASTEXITCODE
For more information on when this will be addressed, you can subscribe to the GitHub issue.