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.
Finding commands
To figure out which commands already exist, you can make a GET
call to the /commands
API endpoint. You can also see commands in the UI at <YOUR_UI_URL>/commands
.
Example commands page:
Using a command
To use a command, define a screwdriver.yaml
that uses the sd-cmd
cli in a step with the format: sd-cmd exec <namespace>/<name>@<version> <arguments>
.
Input:
namespace/name
- the fully-qualified command nameversion
- a semver-compatible format or tagarguments
- passed directly to the underlying format
Output:
All debug logs about the command lookup and execution are stored in $SD_ARTIFACTS_DIR/.sd/commands/namespace/name/version/timestamp.log
In this example, we are using the awscli/install command.
Example screwdriver.yaml
:
jobs:
main:
requires: [~pr, ~commit]
image: node:lts
steps:
- init: sd-cmd exec awscli/install@1.0 -i mySecretID -s secretAccessKey -r us-west-2
Screwdriver will download that binary or script from the Store, make it executable, and run it with the -i mySecretID -s secretAccessKey -r us-west-2
arguments directly:
$ /opt/sd/commands/awscli/install/1.0.1/install.sh -i mySecretID -s secretAccessKey -r us-west-2
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>
.
Binary sd-command.yaml
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 sd-command.yaml
example:
namespace: foo
name: bar
version: '1.0'
description: |
Lorem ipsum dolor sit amet.
maintainer: foo@bar.com
format: habitat # Format the command is in (binary, 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 sd-command.yaml
example:
namespace: foo
name: bar
version: '1.0'
description: |
Lorem ipsum dolor sit amet.
maintainer: foo@bar.com
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
Caveats
- Cannot do the following in a pull request: publish a command, create a tag, delete a tag or command
- A command can only be published by one pipeline
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:lts
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
Removing a command
You can remove your command and all its associated tags and versions by clicking on the trash icon in the UI on the command page.
Note: Do not delete your command pipeline beforehand, because it is required to determine who has permission to delete the command.
More links
*May be out of date.