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({...}).
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 * * *" }),
},
});
workflowsEach workflow's name and its file,
.ts,.jsor.py, relative to the config file. Names are lowercase letters, digits and hyphens.agentsEach agent's definition, made with
agent({...}). See Agents.schedulesEach schedule, made with
schedule(...). They replace every schedule the workspace has. Leaveschedulesout to keep the workspace's;{}removes them all.runnerProfileThe runner image profile that
step.execandstep.activitycalls ask for when they name noprofile, 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 implicitbasethat asks for nothing: any runner of the pool takes the step, as before, anddeployremoves 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 deployreadsshiftlabs.config.ts, then.mts,.jsor.mjs, from the current folder.--config <file>names another.- Each workflow's file can import other files and, in TypeScript, npm packages.
deploysends them with it. See Files and packages. shiftlabs init --template <name>writes a project to start from. See Templates.shiftlabs typeswrites 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,
deployrecords no release, so CI can deploy on every push. deploydeletes 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.
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,@yearlyand@annuallybecome schedules.@reboot, and any line that isn't a comment, a blank line, aNAME=valueline 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 noCRON_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=valuelines setenvfor the entries after them.SHELL=picks the shell,/bin/shby default.MAILTO=isn't imported: choose who hears of a failed run in Settings → Failure alerts. Names starting withSHIFTLABS_are listed and not imported. Cron's ownHOME,LOGNAMEandPATH=/usr/bin:/binaren'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,KEYorCREDENTIALbecomes{ 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 asAPI_KEYafterapi_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, defaultdefault, 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.
--outmust be a new or empty folder.--dry-runprints 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.
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
- Projects in the CLI
Every rule of
shiftlabs deploywith a project. - Releases
Stage, release, roll back and promote.
- Workspace and roles
Who can deploy, and what a workspace holds.
- Runs and steps
What happens once a version is current.