Deploy a VHD

Octopus.Vhd exported 2026-07-22 by Octopus Deploy belongs to ‘Package’ category.

Deploy a VHD from a package and add it to a Hyper-V virtual machine.

Parameters

When this step is included in a project’s deployment process, the parameters below can be set.

VHD application path

Octopus.Action.Vhd.ApplicationPath (required)

The folder within the VHD that contains your application. Octopus will look in this folder when performing substitutions and transforms.

Example: PublishedApps\MyApplication

Add VHD to Hyper-V

Octopus.Action.Vhd.DeployVhdToVm

Attach the VHD to a Hyper-V Virtual Machine.

Allowed values: True, False

Default: False

Virtual machine name

Octopus.Action.Vhd.VmName

The name of the Hyper-V Virtual Machine to update. The VM will be shut down, the VHD will be added replacing the current first virtual drive if there is one, then the VM will be restarted.

Optional features

Enable features by adding their IDs to Octopus.Action.EnabledFeatures (a comma-separated list).

.NET Configuration Transforms `Octopus.Features.ConfigurationTransforms`

Runs configuration file transforms. Enabled by default for package deployments.

Octopus.Action.Package.AutomaticallyRunConfigurationTransformationFiles

Octopus.Action.Package.AutomaticallyRunConfigurationTransformationFiles

Run default XML transforms (True/False).

Octopus.Action.Package.AdditionalXmlConfigurationTransforms

Octopus.Action.Package.AdditionalXmlConfigurationTransforms

Comma- or newline-separated list of additional transform rules (e.g. Web.Release.config => Web.config).

.NET Configuration Variables `Octopus.Features.ConfigurationVariables`

Replace appSettings and connectionStrings in .config files. Enabled by default for package deployments.

Octopus.Action.Package.AutomaticallyUpdateAppSettingsAndConnectionStrings

Octopus.Action.Package.AutomaticallyUpdateAppSettingsAndConnectionStrings

Replace appSettings and connectionStrings in .config files (True/False).

Custom Installation Directory `Octopus.Features.CustomDirectory`

Change where the package is extracted on the target.

Octopus.Action.Package.CustomInstallationDirectory

Octopus.Action.Package.CustomInstallationDirectory

Path on the target to install the package.

Octopus.Action.Package.CustomInstallationDirectoryShouldBePurgedBeforeDeployment

Octopus.Action.Package.CustomInstallationDirectoryShouldBePurgedBeforeDeployment

Purge this directory before installation (True/False).

Octopus.Action.Package.CustomInstallationDirectoryPurgeExclusions

Octopus.Action.Package.CustomInstallationDirectoryPurgeExclusions

Newline-separated list of files/dirs to exclude from purge.

Custom Deployment Scripts `Octopus.Features.CustomScripts`

Execute scripts during the deployment (pre-deploy, deploy, post-deploy) without embedding them in your package.

Octopus.Action.CustomScripts.PreDeploy.

Octopus.Action.CustomScripts.PreDeploy.<ext>

Pre-deploy script body. The key’s is the script language extension: ps1 (PowerShell), sh (Bash), csx (C#), or py (Python).

Octopus.Action.CustomScripts.Deploy.

Octopus.Action.CustomScripts.Deploy.<ext>

Deploy-phase script body. The key’s is the script language extension: ps1 (PowerShell), sh (Bash), csx (C#), or py (Python).

Octopus.Action.CustomScripts.PostDeploy.

Octopus.Action.CustomScripts.PostDeploy.<ext>

Post-deploy script body. The key’s is the script language extension: ps1 (PowerShell), sh (Bash), csx (C#), or py (Python).

Structured Configuration Variables `Octopus.Features.JsonConfigurationVariables`

Replace settings in JSON, YAML, XML, and Java Properties files with Octopus variables. Enabled by default for package deployments.

Octopus.Action.Package.JsonConfigurationVariablesTargets

Octopus.Action.Package.JsonConfigurationVariablesTargets

Newline-separated list of target files (e.g. appsettings.json). Wildcards supported.

Substitute Variables in Templates `Octopus.Features.SubstituteInFiles`

Transforms files using the Octopus #{Variable} substitution syntax. Enabled by default for package deployments.

Octopus.Action.SubstituteInFiles.TargetFiles

Octopus.Action.SubstituteInFiles.TargetFiles

Newline-separated list of file names to transform (relative to package). Wildcards supported.

Octopus.Action.SubstituteInFiles.OutputEncoding

Octopus.Action.SubstituteInFiles.OutputEncoding

Encoding name for the output file (e.g. utf-8). Optional.

Step configuration using OCL

Example in Octopus Configuration Language (OCL):

step "deploy-vhd" {
    name = "Deploy VHD"
    properties = {
        Octopus.Action.TargetRoles = "hyperv-host"
    }

    action {
        action_type = "Octopus.Vhd"
        properties = {
            Octopus.Action.Package.DownloadOnTentacle = "False"
            Octopus.Action.Package.FeedId = "octopus-server-built-in"
            Octopus.Action.Package.PackageId = "MyApp"
            Octopus.Action.RunOnServer = "false"
            Octopus.Action.Vhd.ApplicationPath = "PublishedApps\\MyApp"
            Octopus.Action.Vhd.DeployVhdToVm = "True"
            Octopus.Action.Vhd.VmName = "MyVM"
        }

        packages {
            acquisition_location = "Server"
            feed = "octopus-server-built-in"
            package_id = "MyApp"
        }
    }
}

Page updated on Wednesday, July 22, 2026