Plugins

ssh

This plugin runs a command on another computer over SSH.

  ssh.run(address, { user, key | password, command, input, hostKey, timeout, as })
      gives { status, out, err }

address is the host, with :port when the port is not 22. Each call signs in and runs one command.

Options:

userthe user to sign in as; required keya handle to a secret that holds a private key: PEM text, no passphrase passworda handle to a secret that holds a password; give key or password, not both commandthe command, which the other computer's shell reads; required inputthe command's stdin: text, bytes or a blob hostKeythe other computer's public key ("ssh-ed25519 AAAA..."), its fingerprint ("SHA256:...") or "unchecked"; required timeoutfor the whole call: seconds, or text such as "5m"; default 1m asthe form of out: "text", "bytes", "json" or "blob"; default "text"

Returns:

statusthe exit code; a code other than 0 is not an error outstdout: at most 64 MiB, or a blob of any size, written to the job's scratch directory as the command prints it errstderr, as text: at most 64 MiB

The call refuses a key or a password that is not a handle.
The plugin sends a password as a password and as the answer to a question the server asks.
The call checks the other computer's key against hostKey before it signs in. When they differ, the error gives the fingerprint of the key shown.
With hostKey: "unchecked" the call accepts any key.
The plugin uses no SSH key, agent or known_hosts file of the runner's.

Errors:

refusedthe sign-in was rejected, the key shown is not hostKey, or the connection failed timeoutthe call ran past its timeout not_foundthe host's name could not be resolved bad_inputout or err is over 64 MiB

Needs net:host for the other computer, and secret:NAME@net:host for the key or password.

This script runs uptime on a build server.

allow: [net:build.example, "secret:BUILD_KEY@net:build.example"]

const r = ssh.run("build.example", {
  user: "deploy",
  key: secrets.get("BUILD_KEY"),
  hostKey: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGL60EhV1iO6PGQF8k0yngzkvuC3Kim6+iSe9a5KF0aa",
  command: "uptime",
})
if (r.status !== 0) throw new Error(r.err)
return r.out.trim()
// gives "12:00:00 up 3 days,  2 users,  load average: 0.10, 0.12, 0.09"