Commands

Screwdriver commands are executables which can either be a group of commands in a script or a binary that people can use to replace a step definition in a screwdriver.yaml.

Using a command

To use a command, define a screwdriver.yaml that uses the sd-cmd cli with the format:

$ sd-cmd exec <namespace>/<name>@<version> <arguments>

Input:

Output:

All debug logs about the command lookup and execution are stored in $SD_ARTIFACTS_DIR/.sd/commands/namespace/name/version/timestamp.log

Example:

jobs:
    main:
        requires: [~pr, ~commit]
        steps:
            - exec: sd-cmd exec foo/bar@1 -baz sample

Screwdriver will download that binary or script from the Store, make it executable, and run it with the -baz sample arguments directly:

$ /opt/sd/commands/foo/bar/1.0.1/foobar.sh -baz sample

Creating a command

Publishing and running commands must be done from a Screwdriver pipeline.

Writing a command yaml

To create a command, create a repo with a sd-command.yaml file. The file should contain a namespace, name, version, description, maintainer email, format, and a config that depends on a format. Optionally, you can also set the usage field, which is used for documentation purposes in the UI. If not set, usage will default to sd-cmd exec <namespace>/<name>@<version>.

Example sd-command.yaml:

Binary example:

namespace: foo # Namespace for the command
name: bar # Command name
version: '1.0' # Major and Minor version number (patch is automatic), must be a string
description: |
  Lorem ipsum dolor sit amet.
usage: |
  sd-cmd exec foo/bar@<VERSION> <OPTION> <TARGET>
  Options:
          --config              config file
          --debug               debug mode (default "false")
          --host                super host
          --log-level           set the logging level ("debug"|"info"|"warn"|"error"|"fatal") (default "info")
  Target:                       path to file
maintainer: foo@bar.com # Maintainer of the command
format: binary # Format the command is in (binary, habitat)
binary:
    file: ./foobar.sh # Relative path to script or binary file from sd-command.yaml file or absolute path to it.

Remote Habitat example:

namespace: foo # Namespace for the command
name: bar # Command name
version: '1.0' # Major and Minor version number (patch is automatic), must be a string
description: |
  Lorem ipsum dolor sit amet.
maintainer: foo@bar.com # Maintainer of the command
format: habitat
habitat:
    package: core/node8 # Package of the Habitat command
    mode: remote # Mode the Habitat command (remote, local)
    command: node # Executable of the Habitat command

Local Habitat example:

namespace: foo # Namespace for the command
name: bar # Command name
version: '1.0' # Major and Minor version number (patch is automatic), must be a string
description: |
  Lorem ipsum dolor sit amet.
maintainer: foo@bar.com # Maintainer of the command
format: habitat # Format the command is in (binary, habitat)
habitat:
    package: core/node8 # Package of the Habitat command
    mode: local # Mode of the Habitat command (remote, local)
    file: ./foobar.hart # Relative path to the .hart file from sd-command.yaml file or absolute path to it.
    command: node # Executable of the Habitat command

Writing a screwdriver.yaml for your command repo

To validate your command, run the sd-cmd validate command. -f stands for file (default sd-command.yaml).

To publish your command, run the sd-cmd publish command in a separate job. -f stands for file (default sd-command.yaml). -t stands for tag (default latest).

To tag your command, run the sd-cmd promote command with the format: sd-cmd promote <namespace>/<name> <version> <tag>. You can set exact version or tag (e.g. 1.0.1, latest) at <version>

Example screwdriver.yaml:

shared:
    image: node:8
jobs:
    main:
        requires: [~pr, ~commit]
        steps:
            - validate: sd-cmd validate -f sd-command.yaml
    publish:
        requires: [main]
        steps:
            - publish: sd-cmd publish -f sd-command.yaml -t latest
    promote:
        requires: [publish]
        steps:
            - promote: sd-cmd promote foo/bar latest stable

Finding commands

To figure out which commands already exist, you can make a GET call to the /commands endpoint. See the API documentation for more information. You can also see commands in the UI at <YOUR_UI_URL>/commands.

*May be out of date.