shiftlabs Start free
Menu Projects

Projects

A project is a folder with a shiftlabs.config.ts that lists your workflows. shiftlabs deploy makes all of them current together, as one release.

The config file

shiftlabs.config.ts names each workflow and the file it is in. It can also list agents and schedules, and name the runner image its steps run on. Its default export must be project({...}).

shiftlabs.config.ts
import { project, schedule } from "shiftlabs";

export default project({
  workflows: {
    "refund-check": "./workflows/refund-check.ts",
    "nightly-report": "./workflows/nightly_report.py",
  },
  schedules: {
    nightly: schedule("nightly-report", { cron: "0 3 * * *" }),
  },
});
  • workflows

    Each workflow's name and its file, .ts, .js or .py, relative to the config file. Names are lowercase letters, digits and hyphens.

  • agents

    Each agent's definition, made with agent({...}). See Agents.

  • schedules

    Each schedule, made with schedule(...). They replace every schedule the workspace has. Leave schedules out to keep the workspace's; {} removes them all.

  • runnerProfile

    The runner image profile that step.exec and step.activity calls ask for when they name no profile, such as "network" or "network@2026.11.1". Each workflow version keeps the one it was deployed with, so a rollback brings it back. Left out, the default is an implicit base that asks for nothing: any runner of the pool takes the step, as before, and deploy removes a default the workflows had. A save in the dashboard's workflow editor sends no profile, so the version it makes keeps the default of the one it replaces.

  • shiftlabs deploy reads shiftlabs.config.ts, then .mts, .js or .mjs, from the current folder. --config <file> names another.
  • Each workflow's file can import other files and, in TypeScript, npm packages. deploy sends them with it. See Files and packages.
  • shiftlabs init --template <name> writes a project to start from. See Templates.
  • shiftlabs types writes your workspace's secret and var names next to the config file, for your editor. See Editor types.

Deploy a project

shiftlabs deploy with no files deploys the project to the workspace of SHIFTLABS_API_KEY. It stages each workflow, then makes every workflow, agent and schedule the project lists current together in one release. Nothing goes live until the release does. Projects in the CLI shows each step and what deploy prints.

  • A developer key can deploy a project.
  • When nothing changed, deploy records no release, so CI can deploy on every push.
  • deploy deletes nothing. It lists the workspace's workflows and agents that the project doesn't name, and leaves them as they are.
  • shiftlabs deploy <file>... makes each workflow it names current at once. That isn't a release, and the release history doesn't show it.

Import a crontab

shiftlabs import crontab <file> turns a crontab into a project: a workflow and a schedule for each entry, with the entry's timing, time zone and env. It writes the project and prints what it holds. Nothing reaches the workspace until you deploy it.

shellterminal
npx shiftlabs import crontab crontab.txt --dry-run
crontab -l | npx shiftlabs import crontab - --out cron --timezone America/Detroit
npx shiftlabs import crontab /etc/crontab --system --out system-cron
npx shiftlabs deploy --config cron/shiftlabs.config.ts
  • Five-field entries and the macros @hourly, @daily, @midnight, @weekly, @monthly, @yearly and @annually become schedules. @reboot, and any line that isn't a comment, a blank line, a NAME=value line or an entry, is listed with its line number and not imported.
  • CRON_TZ= sets the time zone of the entries after them. TZ= is passed to the commands after it, as cron does, and is also their schedule's time zone while no CRON_TZ= is in effect, with a note, since cron scheduled those by the host's zone. Entries before either get --timezone, else UTC, and the preview says so. A zone that isn't an IANA name is listed and not imported: it changes no time zone and isn't passed.
  • Other NAME=value lines set env for the entries after them. SHELL= picks the shell, /bin/sh by default. MAILTO= isn't imported: choose who hears of a failed run in Settings → Failure alerts. Names starting with SHIFTLABS_ are listed and not imported. Cron's own HOME, LOGNAME and PATH=/usr/bin:/bin aren't set, unless the crontab sets them: commands get the runner's environment, and the preview says so.
  • A name containing TOKEN, SECRET, PASSWORD, PASSWD, KEY or CREDENTIAL becomes { secret: "NAME" }, with the name in capitals. Its value is never written: create a secret of that name, marked readable, before the first run. The preview lists them. Secret names ignore case, so a second name that differs from an earlier one only in case, such as API_KEY after api_key, is listed and not imported.
  • Each workflow runs its line as cron does, on a runner: command: [shell, "-c", line], with the text after an unescaped % as standard input, % as newlines. \% is a %. It runs on the pool --runner, default default, with no retries, and stops after --timeout, default 10 minutes. Cron had no limit.
  • With --system, the sixth field of each entry is a user. Commands run as the runner's user, and the preview says so.
  • Schedules take overlap: "allow": like cron, a tick starts a run even while the last one is still going.
  • A project deploys as one release of at most 50 workflows, so entries past the 50th are listed and not imported.
  • --out must be a new or empty folder. --dry-run prints the preview and writes nothing. The same crontab always gives the same files.
  • Deploying the project replaces every schedule the workspace has. To keep them, copy the workflows and schedules it wrote into the project that has them.

Releases and rollback

The workspace doesn't store your project. It stores what deploy sends: each workflow's new version, and the release that made them current.

shellterminal
npx shiftlabs deploy
# release 8
#   workflow refund-check: 3f9a0c7e (was 1d9a281e)
#   workflow nightly-report: 8be21f04 (unchanged)
npx shiftlabs releases
npx shiftlabs rollback 7

A rollback makes an earlier release's versions and schedules current again, as a new release. See History and rollback.

Staging and production

Deploy the project to a staging workspace, then promote its release to a linked production workspace with shiftlabs promote <release> --to <workspace>.

A promotion copies the release's workflow versions byte for byte. Each workspace keeps its own secrets, vars and connections, and the target must have the ones the code reads. See Promote a release, and Deploy from GitHub to do it from CI.

Reference