Using the Shell Script Command
One of the steps you can include in a Harness workflow is a Shell Script command step.
With the Shell Script command, you can execute scripts in the shell session of the workflow in the following ways:
- Execute bash or PowerShell scripts on the host running a Harness Delegate. You can use Tags to identify which Harness delegate to use.
- Execute bash or PowerShell scripts on a remote host in the deployment service infrastructure.
When executing a script, you can also dynamically capture the execution output from the script, providing runtime variables based on the script execution context, and export those to another step in the same workflow or another workflow in the same pipeline.
For example, you could use the Shell Script step to capture instance IDs in the deployment environment and then pass those IDs downstream to future workflow steps or phases, or even to other workflows executed in the same pipeline.
What Information is Available to Capture?
Any information in the particular shell session of the workflow can be set, captured and exported using one or more Shell Script steps in that workflow. In addition, you can set and capture information available using the built-in Harness variables. For more information, see Variables and Expressions in Harness.
Capturing and exporting script output in the Shell Script step can be very powerful. For example, a Harness trigger could pass in a variable to a workflow (like a Git commitID), the Shell Step could use that value and info from its session in a complex function, and then export the output down the pipeline for further evaluation.
Before You Begin
- Add a Workflow
- Variables and Expressions in Harness
- Secrets Management (for shell session execution credentials)
Using Shell Script Step
The following procedure provides a simple demonstration of how to create a bash script in a Shell Script step in a workflow and publish its output in a variable.
To capture the shell script output in a variable, do the following:
- In a Harness application, open a workflow. For this example, we will use a Build workflow.
- In a workflow section, click Add Command. The Add Command dialog opens.
- In Add Command, in Others, click Shell Script. The Shell Script dialog appears.
- In Script Type, select BASH or POWERSHELL. In this example, we will use BASH.
- In Script. enter a bash or PowerShell script. In this example, we will use a script that includes an export. For example, export the variable names
For PowerShell, you could set an environment variable using
$Env:BUILD_NO="345"You must use quotes around the value because environment variables are Strings.
- In Script Output, enter the list of variables you want to use. In our example, we would enter BUILD_NO,LANG.
- Where to execute the script? If you wish to execute the script on the host running the Harness delegate, enable Execute on Delegate. Often, you will want to execute the script on a target host. If so, ensure Execute on Delegate is disabled.
- In Target Host, enter the IP address or hostname of the remote host where you want to execute the script. The target host must be in the service infrastructure selected when you created the workflow, and the Harness delegate must have network access to the target host.
- If you selected BASH in Script Type, Connection Type will contain SSH. If you selected POWERSHELL in Script Type, Connection Type will contain WINRM.
- In SSH Connection Attribute (or WinRM Connection Attribute), select the execution credentials to use for the shell session. For information on setting up execution credentials, see Using Execution Credentials.
- In Working Directory, specify the folder where the script is executed on the delegate or remote host, for example /tmp for Linux or %TEMP% for Windows.
- In Tags, enter the tag of the delegate to use. You can add tags to delegate in order to ensure that they are used to execute the command. For more information, see Delegate Tags.
Tagging can be used whether Execute on Delegate is enabled or not. The Shell Script command honors the tag and executes the SSH connection to the specified target host via the tagged delegate.
An example where tagging might be useful when Execute on Delegate is disabled is when you specify an IP address in Target Host, but you have 2 VPCs with the same subnet and duplicate IP numbers exist in both. Using tags, you can scope the the shell session towards the delegate in a specific VPC.
- To export the output variable(s) you entered in Script Output earlier, enable Publish output in the context. If you do not enable this, the variables you entered in Script Output will still be displayed in the deployment details and logs for the workflow.
- In Publish Variable Name, enter a unique parent name for all of the output variables. You will use this name to reference the variable elsewhere. For example, if the Publish Variable Name is checkout, you would reference BUILD_NO with
- In Scope, select Pipeline, Workflow, or Phase. The output variables are available within the scope you set here.
The scope you select is useful for preventing variable name conflicts. You might use a workflow with published variables in multiple pipelines, so scoping the variable to Workflow will prevent conflicts with other workflows in the pipeline.
Here is an example of a complete Shell Script command:
- Click SUBMIT. The Shell Script is added to your workflow.
Next, use the output variables you defined in another command in your phase, workflow, or pipeline, as described below.
Use Published Output Variables
The following procedure demonstrates how to use the output variables you captured and published in the Shell Script command above.
Remember that where you can reference your published output variables depends on the scope you set in Scope in the Shell Script command.
To use published output variables, do the following:
- In your Harness workflow, add a new command. For this example, we will use a HTTP command.
Click Add Command. In the Add Command dialog, click HTTP. The HTTP command dialog opens.
- In URL, enter a URL that references the Publish Variable Name
checkoutand Script Output variable names
LANGyou published in the Shell Script command. For example, here is a search using the variables:
Note the use of
- Fill out the rest of the HTTP dialog and click SUBMIT.
When you deploy your workflow, you will see both the Shell Script and HTTP steps using the output variables.
In the log for the Shell Script step, you can see the output variables:
INFO 2018-10-22 14:03:36 Executing command ...
INFO 2018-10-22 14:03:37 Script output:
INFO 2018-10-22 14:03:37 BUILD_NO=345
INFO 2018-10-22 14:03:37 LANG=en-us
INFO 2018-10-22 14:03:37 Command completed with ExitCode (0)
In the log for the HTTP step, you see that the published variables that were used to create this URL
Are now substituted with the output variable values to form the final URL
var is a reserved word for Output and Publish Variable names in the Shell Script step.
If you must use
var, you can use single quotes and
get() when referencing the published output variable.
Instead of using