Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 1 addition & 9 deletions src/pages/docs/deployments/custom-scripts/error-handling.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2025-05-19
modDate: 2026-08-11
title: Error handling
description: Error handling for scripts in Octopus.
icon: fa-solid fa-circle-exclamation
Expand Down Expand Up @@ -80,14 +80,6 @@ FailStep("A friendly message");
fail_step "A friendly message"
```

</details>
<details data-group="error-handling">
<summary>F#</summary>

```fsharp
Octopus.failStep "A friendly message"
```

</details>
<details data-group="error-handling">
<summary>Python3</summary>
Expand Down
5 changes: 2 additions & 3 deletions src/pages/docs/deployments/custom-scripts/index.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2025-05-19
modDate: 2026-08-11
title: Custom scripts
description: Custom scripts allows you to script anything you want using PowerShell, Dotnet Script, F#, Python, or Bash.
description: Custom scripts allows you to script anything you want using PowerShell, Dotnet Script, Python, or Bash.
icon: fa-solid fa-file-code
navOrder: 150
---
Expand All @@ -18,7 +18,6 @@ Octopus supports the following scripting environments:
- Bash scripts (.sh)
- Python scripts (.py)
- C# scripts (.csx) using [dotnet-script](https://github.com/dotnet-script/dotnet-script)
- F# scripts (.fsx)

Octopus can run these scripts on almost any operating system as long as the script runtime is installed and configured correctly.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2025-08-06
modDate: 2026-08-11
title: Logging messages from scripts
description: When your scripts emit messages Octopus will display the messages in the Task Logs at the most appropriate level for the message.
icon: fa-solid fa-clock-rotate-left
Expand Down Expand Up @@ -52,19 +52,6 @@ echoerror() { echo "$@" 1>&2; }
echoerror "You can even define your own function to echo an error!"
```

</details>
<details data-group="logging-messages-in-scripts">
<summary>F#</summary>

```fsharp
printfn "This will be logged as Information"
writeVerbose "Verbose!!"
writeHighlight "This is a highlight"
writeWait "Deployment is waiting on something"
writeWarning "Warning"
eprintfn "This will be logged as Error"
```

</details>
<details data-group="logging-messages-in-scripts">
<summary>Python3</summary>
Expand Down Expand Up @@ -134,15 +121,6 @@ update_progress 10
update_progress 50 "We're halfway there!"
```

</details>
<details data-group="deployments-custom-scripts-logging-messages">
<summary>F#</summary>

```fsharp
Octopus.updateProgress 10
Octopus.updateProgress 50 "We're halfway there!"
```

</details>
<details data-group="deployments-custom-scripts-logging-messages">
<summary>Python3</summary>
Expand All @@ -169,20 +147,6 @@ private static string EncodeServiceMessageValue(string value)
Console.WriteLine("##octopus[progress percentage='{0}' message='{1}']", EncodeServiceMessageValue(percentage.ToString()), EncodeServiceMessageValue(message));
```

</details>
<details data-group="deployments-custom-scripts-progress-service-message">
<summary>F#</summary>

```fsharp
let private encode (value:string) = System.Text.Encoding.UTF8.GetBytes(value) |> Convert.ToBase64String
let private writeServiceMessage name content = printfn "##octopus[%s %s]" name content
let updateProgress (percentage: int) message =
let encodedMessage = message |> encode
let encodedPercentage = percentage.ToString() |> encode
let content = sprintf "percentage='%s' message='%s'" encodedPercentage encodedMessage
writeServiceMessage "progress" content
```

</details>
<details data-group="deployments-custom-scripts-progress-service-message">
<summary>Python3</summary>
Expand Down
25 changes: 1 addition & 24 deletions src/pages/docs/deployments/custom-scripts/output-variables.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2025-05-19
modDate: 2026-08-11
title: Output variables
description: Your scripts can emit variables that are available in subsequent deployment steps.
icon: fa-solid fa-file-export
Expand Down Expand Up @@ -35,14 +35,6 @@ SetVariable("AppInstanceName", "MyAppInstance");
set_octopusvariable "AppInstanceName" "MyAppInstance"
```

</details>
<details data-group="creating-an-output-variable">
<summary>F#</summary>

```fsharp
Octopus.setVariable "AppInstanceName" "MyAppInstance"
```

</details>
<details data-group="creating-an-output-variable">
<summary>Python3</summary>
Expand Down Expand Up @@ -78,21 +70,6 @@ var appInstanceName = OctopusParameters["Octopus.Action[Determine App Instance N
appInstanceName=$(get_octopusvariable "Octopus.Action[Determine App Instance Name].Output.AppInstanceName")
```

</details>
<details data-group="using-variable-in-another-step">
<summary>F#</summary>

```fsharp
//throw if not found
let appInstanceName1 = Octopus.findVariable "Octopus.Action[Determine App Instance Name].Output.AppInstanceName"

//supply a default value to use if not found
let appInstanceName2 = Octopus.findVariableOrDefault "Value if not found" "Octopus.Action[Determine App Instance Name].Output.AppInstanceName"

//return an Option type
let appInstanceName3 = Octopus.tryFindVariable "Octopus.Action[Determine App Instance Name].Output.AppInstanceName"
```

</details>
<details data-group="using-variable-in-another-step">
<summary>Python3</summary>
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2025-05-19
modDate: 2026-08-11
title: Passing parameters to scripts
description: Octopus can pass parameters to your custom script files for any of the supported scripting languages.
icon: fa-solid fa-arrow-right-to-bracket
Expand All @@ -14,21 +14,17 @@ Octopus can pass parameters to your custom script files for any of the supported

Consider this example PowerShell script:

**PowerShell script using Octopus Variables**

```powershell
```powershell PowerShell script using Octopus Variables
$environment = $OctopusParameters["Octopus.Environment.Name"]
Write-Host "Environment: $environment"
```

You can parameterize this script making it easier to test outside of Octopus:

**PowerShell script using parameters**

```powershell
```powershell PowerShell script using parameters
param (
[Parameter(Mandatory=$True)]
[string]$Environment
[Parameter(Mandatory=$True)]
[string]$Environment
)
Write-Host "Environment: $Environment"
```
Expand All @@ -50,20 +46,16 @@ Don't forget to correctly delimit your parameters correctly for the scripting en

You can pass parameters to PowerShell scripts as if you were calling the script yourself from PowerShell, using positional or named parameters.

**Script Parameters in Octopus**

```bash
```bash Script Parameters in Octopus
-Environment "#{Octopus.Environment.Name}" -StoragePath "#{MyApplication.Storage.Path}"
```

**Usage in PowerShell script**

```powershell
```powershell Usage in PowerShell script
Param (
[Parameter(Mandatory=$True)]
[string]$Environment,
[Parameter(Mandatory=$True)]
[string]$StoragePath
[Parameter(Mandatory=$True)]
[string]$Environment,
[Parameter(Mandatory=$True)]
[string]$StoragePath
)

Write-Host "$Environment storage path: $StoragePath"
Expand All @@ -73,15 +65,11 @@ Write-Host "$Environment storage path: $StoragePath"

You can pass parameters to C# scripts [as described here for the dotnet-script engine](https://github.com/dotnet-script/dotnet-script#passing-arguments-to-scripts).

**Script Parameters in Octopus**

```bash
```bash Script Parameters in Octopus
-- "#{Octopus.Environment.Name}" "#{MyApplication.Storage.Path}"
```

**Usage in C# script**

```csharp
```csharp Usage in C# script
var environment = Args[0]
var storagePath = Args[1]
Console.WriteLine("{0} storage path: {1}", environment, storagePath);
Expand All @@ -91,54 +79,30 @@ Console.WriteLine("{0} storage path: {1}", environment, storagePath);

You can pass parameters to Bash scripts [as described in Bash manual.](https://www.gnu.org/software/bash/manual/bash.html#Positional-Parameters)

**Script Parameters in Octopus**

```powershell
```powershell Script Parameters in Octopus
"#{Octopus.Environment.Name}" "#{MyApplication.Storage.Path}"
```

**Usage in Bash script**

```bash
```bash Usage in Bash script
environment="$1"
storagePath="$2"
echo "$environment storage path: $storagePath"
```

## Passing parameters to F# scripts \{#passing-parameters-fsharp}

You can pass parameters to FSharp scripts [as described by the F# documentation.](https://docs.microsoft.com/en-us/dotnet/fsharp/tools/fsharp-interactive/#using-the-fsi-object-in-f-code)

**Script Parameters in Octopus**

```powershell
"#{Octopus.Environment.Name}" "#{MyApplication.Storage.Path}"
```

**Usage in F# script**

```fsharp
let environment = fsi.CommandLineArgs.[1]
let storagePath = fsi.CommandLineArgs.[2]
printfn "$s storage path: $s" environment storagePath
```

## Passing parameters to Python3 scripts \{#passing-parameters-python}

You can pass parameters to python scripts [as described by the python documentation.](https://docs.python.org/3/tutorial/interpreter.html#argument-passing)

**Script Parameters in Octopus**

```python
```python Script Parameters in Octopus
'#{Octopus.Environment.Name}' '#{MyApplication.Storage.Path}'
```
**Usage in Python3 script**

```python
```python Usage in Python3 script
environment=sys.argv[1]
storagePath=sys.argv[2]
print("Parameters {} {}".format(environment, storagePath))
```

:::div{.hint}
**Note:** If your python scripts make use of [argparse](https://docs.python.org/3/library/argparse.html), it's possible you might encounter an error at execution time, as Calamari bootstraps the execution of the python script as part of the deployment or runbook run.
:::
41 changes: 1 addition & 40 deletions src/pages/docs/deployments/custom-scripts/script-modules.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2026-04-27
modDate: 2026-08-11
title: Script modules in Octopus
navTitle: Script modules
description: Script modules allow users to create collections of functions that can be used in deployment processes across multiple projects.
Expand Down Expand Up @@ -95,7 +95,6 @@ Each language has a slightly different syntax for using the Script Module. Pleas
- [PowerShell](#powershell)
- [Bash](#bash)
- [C#](#csharp-script-modules)
- [F#](#fsharp-script-modules)
- [Python](#python-script-modules)

## PowerShell script modules {#powershell}
Expand Down Expand Up @@ -177,44 +176,6 @@ Call it from your Script Step with:
SayHello("George");
```

## F# script modules {#fsharp-script-modules}

F# Script Modules are written as an `.fsx` file next to your script. Import them
via `#load "MyScriptModule.fsx"`, where `MyScriptModule` is the name of your Script
Module with invalid characters removed. The help text above the Script Module body
will show the filename that will be created.

F# script modules need to declare a module name at the top of the Script Module body with `module MyModule`.

Once the Script Module file is loaded, you can either use the functions from the Script Module by prefixing the functions with the module name, or by "opening" the Script Module with `open MyModule`:

```fsharp
#load "MyScriptModule.fsx"
// call the function in the module directly
let result = MyModule.add 1 3
// Or, open the module, and import the functions into scope
open MyModule
let result = add 1 3
```

The `#load` statement must be at the top of your script.

Given an F# Script Module called `FSharp Script Module`:

```fsharp
module MyFSharpScriptModule
let sayHello name =
printfn "Hello %s. Welcome to Octopus!" name;
```

Call it from your Script Step with:

```fsharp
#load "FSharpScriptModule.fsx"
open MyFSharpScriptModule
sayHello "George";
```

## Python script modules {#python-script-modules}

Python Script Modules are written as a `.py` file next to your script. Import them
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2024-08-28
modDate: 2026-08-11
title: Scripts in packages
description: Octopus will run scripts included in your package when the script matches a naming convention.
icon: fa-solid fa-cubes
Expand Down Expand Up @@ -82,8 +82,8 @@ If you are deploying the same package to multiple platforms, you can:

The platform-specific priority order Octopus uses to select scripts is:

- Linux: Bash, Python, C#, F#, PowerShell
- Windows: PowerShell, Python, C#, F#, Bash
- Linux: Bash, Python, C#, PowerShell
- Windows: PowerShell, Python, C#, 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.

Expand All @@ -104,13 +104,13 @@ 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**.

:::figure
![](/docs/img/deployments/custom-scripts/scripts-in-packages/3277766.png)
![The Visual Studio file properties pane for Deploy.ps1, with Build Action set to Content](/docs/img/deployments/custom-scripts/scripts-in-packages/3277766.png)
:::

If you are using OctoPack to package a Windows Service or console application, set **Copy to Output Directory** = **Copy if newer**.

:::figure
![](/docs/img/deployments/custom-scripts/scripts-in-packages/3277765.png)
![The Visual Studio file properties pane for Deploy.ps1, with Copy to Output Directory set to Copy if newer](/docs/img/deployments/custom-scripts/scripts-in-packages/3277765.png)
:::

Read more about [using OctoPack](/docs/packaging-applications/create-packages/octopack).
Expand Down
Loading