Deploy a Windows Service

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

Deploy the contents of a package and configure a Windows Service.

Parameters

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

Install a Windows Service

Octopus.Action.WindowsService.CreateOrUpdateService

If enabled, Tentacle will use sc.exe to attempt to create a Windows Service using the settings below. If the service already exists, Tentacle will stop the service, reconfigure it, and start it again.

Allowed values: True, False

Default: True

Service name

Octopus.Action.WindowsService.ServiceName (required)

The name of the Windows Service to create or configure.

Display name

Octopus.Action.WindowsService.DisplayName

Optional display name of the Windows Service.

Description

Octopus.Action.WindowsService.Description

User-friendly description of the service.

Executable path

Octopus.Action.WindowsService.ExecutablePath (required)

Path to the executable file for the service. The path should be relative to the package installation directory.

Example: MyService.exe

Arguments

Octopus.Action.WindowsService.Arguments

Command line arguments that will be passed to the service when it starts each time.

Service account

Octopus.Action.WindowsService.ServiceAccount

Which built-in account will the service run under.

Allowed values: LocalSystem, NT Authority\NetworkService, NT Authority\LocalService, _CUSTOM

Default: LocalSystem

Custom account name

Octopus.Action.WindowsService.CustomAccountName

The Windows/domain account of the custom user that the service will run under. You will need to ensure that this user has the ‘Log on as a service’ right.

Example: YOURDOMAIN\YourAccount

Custom account password

Octopus.Action.WindowsService.CustomAccountPassword

The password for the custom account given above.

Start mode

Octopus.Action.WindowsService.StartMode

When will the service start. Use Unchanged to use the current status.

Allowed values: auto, delayed-auto, demand, disabled, unchanged

Default: auto

State

Octopus.Action.WindowsService.DesiredStatus

Defines the state of the service after it has been deployed. Started will start the service. Stopped will leave the service stopped. Unchanged will start the service if it already existed and was running. Default will start the service if the start mode is Automatic or Automatic (delayed).

Allowed values: Started, Stopped, Unchanged, Default

Default: Default

Dependencies

Octopus.Action.WindowsService.Dependencies

Any dependencies that the service has. Separate the names using forward slashes (/).

Example: LanmanWorkstation/TCPIP/MSSQL

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.

PowerShell Edition `Octopus.Features.SelectPowerShellEditionForWindows`

Specify the edition of PowerShell used during deployments on Windows.

Octopus.Action.PowerShell.Edition

Octopus.Action.PowerShell.Edition

PowerShell edition on Windows (Desktop or Core).

Allowed values: Desktop, Core

Step configuration using OCL

Example in Octopus Configuration Language (OCL):

step "deploy-windows-service" {
    name = "Deploy Windows Service"
    properties = {
        Octopus.Action.TargetRoles = "app-server"
    }

    action {
        action_type = "Octopus.WindowsService"
        properties = {
            Octopus.Action.Package.DownloadOnTentacle = "False"
            Octopus.Action.Package.FeedId = "octopus-server-built-in"
            Octopus.Action.Package.PackageId = "MyService"
            Octopus.Action.RunOnServer = "false"
            Octopus.Action.WindowsService.CreateOrUpdateService = "True"
            Octopus.Action.WindowsService.DesiredStatus = "Default"
            Octopus.Action.WindowsService.DisplayName = "My Service"
            Octopus.Action.WindowsService.ExecutablePath = "MyService.exe"
            Octopus.Action.WindowsService.ServiceAccount = "LocalSystem"
            Octopus.Action.WindowsService.ServiceName = "MyService"
            Octopus.Action.WindowsService.StartMode = "auto"
        }

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

Page updated on Wednesday, July 22, 2026