Add a script step to runbook

This script demonstrates how to programmatically add a simple PowerShell script to a runbook.


Provide values for the following:

  • Octopus URL
  • Octopus API Key
  • Name of the space to use
  • Name of the runbook
  • Source PowerShell script
  • Optional Target role to run the script against.

Note: The source script provided to Octopus must be properly escaped.


// If using .net Core, be sure to add the NuGet package of System.Security.Permissions
#r "path\to\Octopus.Client.dll"

using Octopus.Client;
using Octopus.Client.Model;

// Declare working variables
var octopusURL = "https://youroctourl";
var octopusAPIKey = "API-YOURAPIKEY";
var spaceName = "default";
var runbookName = "MyRunbook";
var stepName = "My new step";
var role = "target-role";
var scriptToRun = "Write-Host \"Hello World\" ";

// Create repository object
var endpoint = new OctopusServerEndpoint(octopusURL, octopusAPIKey);
var repository = new OctopusRepository(endpoint);
var client = new OctopusClient(endpoint);

    // Get space
    var space = repository.Spaces.FindByName(spaceName);
    var repositoryForSpace = client.ForSpace(space);

    // Get runbook
    var runbook = repositoryForSpace.Runbooks.FindOne(n => n.Name == runbookName);
    var processId = runbook.RunbookProcessId;

    var runbookProcess = repositoryForSpace.RunbookProcesses.Get(processId);

    // Check for existing step.
    if (runbookProcess.Steps.Any(s => s.Name == stepName))
        Console.WriteLine("Existing step present with same name, please check and try again");

    // Create PowerShell script step
    var step = new Octopus.Client.Model.DeploymentStepResource
        Name = stepName,
        Condition = DeploymentStepCondition.Success,
        PackageRequirement = DeploymentStepPackageRequirement.LetOctopusDecide,
        StartTrigger = DeploymentStepStartTrigger.StartAfterPrevious

    var stepAction = new DeploymentActionResource
        ActionType = "Octopus.Script",
        Condition = DeploymentActionCondition.Success,
        Name = stepName

    var runOnServer = false;
    if(!string.IsNullOrWhiteSpace(role)) {
        runOnServer = true;

    // Add step action properties
    stepAction.Properties.Add("Octopus.Action.RunOnServer", new Octopus.Client.Model.PropertyValueResource(runOnServer.ToString()));
    stepAction.Properties.Add("Octopus.Action.Script.ScriptSource", new Octopus.Client.Model.PropertyValueResource("Inline"));
    stepAction.Properties.Add("Octopus.Action.Script.ScriptBody", new Octopus.Client.Model.PropertyValueResource(scriptToRun));
    stepAction.Properties.Add("Octopus.Action.Script.Syntax", new Octopus.Client.Model.PropertyValueResource("PowerShell"));

    // optional target role
    if(!string.IsNullOrWhiteSpace(role)) {
        step.Properties.Add("Octopus.Action.TargetRoles", new Octopus.Client.Model.PropertyValueResource(role));

    // Add step to Actions

    // Add PowerShell script step to process

    // Update runbook process
catch (Exception ex)

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Sunday, January 1, 2023