Shell command

Run a shell command on an agent; its spool output set values become the node’s output.

The command runs on an agent with the shell capability. The managed environments have one, so a shell step needs nothing set up.

• Kind: shell
• Palette: Activities
• Run it on its own: yes

When to use

• A command you would type yourself: a build, a deploy script, a curl with flags.
• Anything that needs tools installed where it runs.

For more than a few lines, or a script in another language, use a code node.

Configuration

Field	Type	Required	Description
run	string	yes	The shell command to run.
credentials	object	no	Named credentials injected as env vars: {ENV_VAR: credential_name}.
env	object	no	Extra environment variables, as a JSON object.
optional_when_untrusted	boolean	no	Run without the credential when the run is untrusted (a fork pull request), instead of failing. The credential is still withheld.
outputs	object	no	Rename what comes out: {output_name: key_in_the_raw_output}. Absent passes the raw output through.

Output

An object whose keys depend on the configuration.

Example

version: hyperspool-graph/v1
nodes:
  - id: build
    type: shell
    config:
      run: spool output set tag=v1.2.3
  - id: ship
    type: shell
    config:
      run: { $template: "./deploy.sh {{ nodes.build.output.tag }}" }
      credentials: { DEPLOY_TOKEN: deploy-token }
edges:
  - { from: build, to: ship }

spool output set inside the command sets the node’s output, so ship reads the tag as nodes.build.output.tag. credentials puts the project credential deploy-token in $DEPLOY_TOKEN for this step only; the document names the credential and never holds its value. A non-zero exit fails the step.

See the node reference for every other node.