When deploying a package, you can hook into the deployment process at different stages to perform custom actions. You do this by adding specially named scripts at the root of your package.
Supported scripts
You can add any of the following script files in any of the scripting languages supported by Octopus to your packages:
PreDeploy.<ext>Deploy.<ext>PostDeploy.<ext>DeployFailed.<ext>
Where <ext> is the appropriate extension for your scripting language of choice. Also note these file names will be case sensitive on certain operating systems.
Octopus will detect these scripts and invoke them at the appropriate time during the step. Which file you use depends on when you need your custom activity to run; see the section on what order are conventions run in for details. Your scripts can do anything your scripting language supports, as well as setting output variables and collecting artifacts.
Supported steps
The following steps have been designed to support running scripts; either at the root of a package, inline or both:
- Deploy to IIS
- Deploy a Windows Service
- Deploy a Package
- Deploy an Azure Web App
- Deploy an Azure App Service
- Deploy an Azure Resource Manager template
- Deploy a Service Fabric App
- Deploy to NGINX
- Deploy Java Archive
- Deploy a VHD image
- Deploy to Tomcat via Manager
- Deploy to Wildfly or EAP
- Upgrade a Helm Chart
However, not all package steps support script hooks. As a general rule, any of the built-in step templates or community step templates that have the Custom Deployment Scripts feature available in the configuration features dialog support script hooks:
Note: The Custom Deployment Scripts feature only needs to be enabled if you want to define your scripts inline instead of executing scripts at the root of a package.
Including the scripts in the package
- Create the scripts you want Octopus to execute during the step.
- Name each script to match the naming convention depending when you want the script to execute.
- Include these scripts at the root of your package. Octopus does not search subdirectories.
Running a script when a step fails
You can create a file named DeployFailed.<ext>, which will be invoked if the step fails. Our blog post about this feature describes how DeployFailed.
How Octopus executes your scripts
At each stage during the deployment, Octopus will look for a scripts matching the current stage, and execute the first matching script it finds ordered by a platform-specific priority (see cross-platform support).
- Octopus extracts the package to new uniquely named directory. This becomes the current working directory.
- Octopus does some work, then executes
PreDeploy.<ext>in the current working directory. - Optional: If you are using the custom installation directory feature, Octopus will copy the contents of the current working directory to the custom installation directory. This becomes the current working directory.
- Octopus does some work, then executes
Deploy.<ext>in the current working directory. - Octopus does some work, then executes
PostDeploy.<ext>in the current working directory.
For more details see how packages are deployed and what order are conventions run in.
Cross-platform support
If you are deploying the same package to multiple platforms, you can:
- Use a single scripting language common to all platforms. Octopus will run the single script using the same scripting runtime on all platforms.
- Use the scripting language most native to each platform. Octopus will run the most appropriate script for each platform using a platform-specific priority order.
The platform-specific priority order Octopus uses to select scripts is:
- Linux: Bash, Python, C#, F#, Powershell
- Windows: Powershell, Python, C#, F#, Bash
Example: You are deploying an application to both Windows and Linux. You can write a single PreDeploy.py python script, making sure the python runtime is installed on both platforms. Alternatively, you can write both PreDeploy.sh and PreDeploy.ps1, and Octopus will run the Bash script on Linux and the PowerShell script on Windows.
Disabling this convention
You can prevent Octopus from automatically running scripts in packages by adding the Octopus.Action.Package.RunScripts variable to your project and setting it to false. You can scope the value of this variable to suit your needs.
Defining your scripts inline
Rather than embed scripts in packages, you can also define scripts within the step definition using the Octopus user interface. This is a feature that can be enabled on certain steps by clicking CONFIGURE FEATURES and selecting Custom Deployment Scripts.
When enabled, you will see Custom Deployment Scripts under the features section of the process definition.
Troubleshooting
Make sure the scripts are located in the root of your package.
Make sure the scripts are actually included in your package. Extract your package and inspect the contents to make sure the scripts are included as you expect. For example, if you are using OctoPack for an ASP.NET web application, you’ll need to make sure the file is marked as Build Action = Content.
If you are using OctoPack to package a Windows Service or console application, set Copy to Output Directory = Copy if newer.
Read more about using OctoPack.
If the scripts in your package are still not running, make sure someone has not set a project variable called Octopus.Action.Package.RunScripts to false for the step where the scripts should run.
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Sunday, January 1, 2023