Shipplane
  • English

      • Registry

      Shipplane Lite ships with 3 built-in task types. Every workflow task's type must be one of the following, or one you've added yourself — see Custom task types below.

      Fetch the live definitions (with per-param descriptions) from a running instance:

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

      @shipplane/pulumi_install

      Installs the Pulumi CLI, used internally by @shipplane/remote_cmd. No params.

      { "id": "install-pulumi", "type": "@shipplane/pulumi_install" }

      @shipplane/local_cmd

      Runs a command on the local machine.

      ParamTypeRequiredDescription
      cmdmultilineyesCommand to execute locally.
      cwdstringnoWorking directory for the command.
      {
  "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.

      ParamTypeRequiredDescription
      cmd_createmultilineyesCommand executed when cmd_type is "up".
      cmd_deletemultilinenoCommand executed when cmd_type is "destroy".
      cmd_typestringyes"up" or "destroy".
      ssh_hoststringyesSSH server hostname.
      ssh_portnumberyesSSH server port.
      ssh_userstringyesSSH username.
      ssh_private_keystringyesPath to the SSH private key file.
      {
  "id": "deploy",
  "type": "@shipplane/remote_cmd",
  "params": {
    "cmd_create": "docker compose up -d",
    "cmd_delete": "docker compose down",
    "cmd_type": "up",
    "ssh_host": "203.0.113.10",
    "ssh_port": 22,
    "ssh_user": "deploy",
    "ssh_private_key": "/home/me/.ssh/id_ed25519"
  }
}

      Example: deploying to a VPS over SSH

      A two-task workflow: install Pulumi (used internally by remote_cmd), then start the app via docker compose on the remote host.

      const deploy = workflow("deploy-app")
  .task("install-pulumi", { type: "@shipplane/pulumi_install" })
  .task("bring-up", {
    type: "@shipplane/remote_cmd",
    dependsOn: ["install-pulumi"],
    params: {
      cmd_create: "docker compose up -d",
      cmd_type: "up",
      ssh_host: "203.0.113.10",
      ssh_port: 22,
      ssh_user: "deploy",
      ssh_private_key: "/home/me/.ssh/id_ed25519",
    },
  });

      Custom task types

      Add your own task types by passing one TaskRegistry under registry in your config file. It's merged on top of the 3 built-in types — it extends the registry, it doesn't replace it.

      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,
};

      Only one TaskRegistry is accepted — register every custom task type on that same registry instance rather than building several and passing one in.