Documentation and SupportDocumentation and Support

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 varibles
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.Actiom.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

Last updated Sunday, January 1, 2023