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 binary config with a path to file.

Example sd-command.yaml:

namespace: foo # Namespace for the command
name: bar # Command name
version: 1.0 # Major and Minor version number (patch is automatic)
description: |
  Lorem ipsum dolor sit amet.
maintainer: foo@bar.com # Maintainer of the command
format: binary # Format the command is in (binary)
binary:
    file: ./foobar.sh # Path to script or binary file from repository root

Writing a screwdriver.yaml for your command repo

To validate your command, run the command-validate script from the screwdriver-command-validator npm module. This means the build image must have NodeJS and NPM properly installed to use it.

To publish your command, run the sd-cmd publish command in a separate job. -f stands for file.

Example screwdriver.yaml:

shared:
    image: node:6
jobs:
    main:
        requires: [~pr, ~commit]
        steps:
            - install: npm install screwdriver-command-validator
            - validate: ./node_modules/.bin/command-validate -f sd-command.yaml
    publish:
        requires: [main]
        steps:
            - publish: sd-cmd publish -f sd-command.yaml

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.

*May be out of date.