#Registry

Shipplane Lite includes two built-in task types. Each workflow task must use one of these types or a custom task type.

Fetch the live definitions, including parameter descriptions, from a running instance:

curl http://localhost:3000/api/v1/registry

#@shipplane/local_cmd

Runs a command on the local machine.

{
  "id": "build",
  "type": "@shipplane/local_cmd",
  "params": { "cmd": "npm run build", "cwd": "./app" }
}

#@shipplane/remote_cmd

Runs a command on a remote host over SSH.

{
  "id": "deploy",
  "type": "@shipplane/remote_cmd",
  "params": {
    "cmd": "cd /srv/app\ndocker compose pull\ndocker compose up -d",
    "ssh_host": "203.0.113.10",
    "ssh_port": 22,
    "ssh_user": "deploy",
    "ssh_private_key": "/home/me/.ssh/id_ed25519"
  }
}

The command runs under bash when the host has it, otherwise sh, with set -e and — where the shell supports it — set -o pipefail. A multi-line command stops at the first failing line.

#Host key verification

On the first connection to a host, its key fingerprint is pinned to ~/.shipplane/known_hosts.json. Later connections fail if the key changes.

Rebuilding a host gives it a new key. To trust the new one, remove that host's entry from ~/.shipplane/known_hosts.json and run again.

#Exit codes

The task output is the command's exit code as a string, readable by dependent tasks via ctx.outputs.

By default a non-zero exit fails the task. Set allow_failure: true to let the workflow continue and branch on the code instead:

const deploy = workflow("deploy-app")
  .task("healthcheck", {
    type: "@shipplane/remote_cmd",
    params: {
      cmd: "curl -fsS localhost:8080/health",
      allow_failure: true,
      ssh_host: "203.0.113.10",
      ssh_port: 22,
      ssh_user: "deploy",
      ssh_private_key: "/home/me/.ssh/id_ed25519",
    },
  })
  .task("rollback", {
    type: "report-status",
    dependsOn: ["healthcheck"],
  });

A command killed by a signal has no exit code, so it fails the task even with allow_failure set.

Task params are passed through verbatim, so reading another task's output needs a custom task type — ctx.outputs["healthcheck"] holds the string.

#Custom task types

Add task types by assigning one TaskRegistry to registry in your config file. Custom types extend the two built-in types rather than replacing them.

import { createTaskRegistry } from "@shipplane/core";

const registry = createTaskRegistry().register("send-slack", {
  run: async (ctx) => {
    await fetch(String(ctx.params.webhook_url), {
      method: "POST",
      body: JSON.stringify({ text: ctx.params.message }),
    });
  },
});

export default {
  http: { addr: "0.0.0.0", port: 4000 },
  registry,
};

The config accepts one TaskRegistry. Register every custom task type on that registry instance.