Cronjobs

A cronjob runs a container on a schedule. It is the heavy-weight scheduled-job option: each run is a fresh Kubernetes CronJob pod, either built from a Git repository or run directly from a public container image. Cronjobs give you a full build environment, arbitrary languages, and their own execution history with captured logs.

Paid feature

Cronjobs are a paid-only feature — creating one requires an active paid plan. For a lighter option that runs an existing edge function on a schedule (no container), see scheduled functions.

Two image sources

A cronjob runs from one of two sources, selected by imageSource:

imageSource	What it does	Required fields
github	Builds a container from a Git repo, then runs it on schedule.	repositoryName (owner/repo), plus branch, language, and build/start commands.
public_image	Runs a public image (e.g. nginx:latest) directly.	publicImage; an optional command override.

The schema enforces this: repositoryName is required when imageSource is github, and publicImage is required when imageSource is public_image.

The schedule

Cronjobs use a 5-field cron expression (minute, hour, day-of-month, month, day-of-week), max 120 characters — for example */5 * * * * runs every five minutes. See scheduled functions for more examples.

Instance tiers

Each run gets a compute tier, set with instanceType:

Tier	Notes
micro	Default.
mini
large
xlarge

Languages

For github cronjobs, language selects the build path:

Language	Value
Node.js	nodejs (default)
Python	python
Go	go
Docker	docker (uses the repo’s own Dockerfile)

Create fields

Field	Type	Default	Notes
name	string	—	1–52 chars, RFC-1123 label. Kept short to leave room for the manual-run suffix.
imageSource	enum	github	github | public_image.
cronSchedule	string	—	5-field cron, 1–120 chars.
region	string	us	Only us exists today.
instanceType	enum	micro	micro | mini | large | xlarge.
repositoryName	string	—	owner/repo; required for github.
branch	string	main
isPublic	boolean	true	Private repos require the GitHub App installation.
language	enum	nodejs	nodejs | python | go | docker.
baseDir	string	./
buildCmd	string	''
startCmd	string	''
dockerfilePath	string	./Dockerfile
dockerBuildContextDir	string	./
autoDeploy	boolean	false
publicImage	string	—	e.g. nginx:latest; required for public_image.
command	string	''	Optional command override for a public image.
env	array	[]	[{ name, value }], plaintext on the wire.
secrets	array	[]	Stored encrypted, never returned.

The name gets a random hex suffix on create (it becomes the Kubernetes CronJob name), kept to 52 characters so the manual-run suffix fits.

Lifecycle and actions

Cronjobs support full CRUD plus lifecycle actions. Every mutation writes the cronjob row change and a transactional outbox row in one database transaction, which is published to worker-v3 to apply or remove the Kubernetes CronJob.

Action	What it does	Outbox topic
Create	Provision the cronjob and its schedule.	cronjob.upsert
Update	Change metadata and redeploy. The source and name are immutable.	cronjob.upsert
Pause	Suspend the schedule (stops firing).	cronjob.upsert
Resume	Re-enable a paused schedule.	cronjob.upsert
Run now	Trigger a manual run immediately.	cronjob.upsert
Delete	Remove the cronjob and its Kubernetes CronJob.	cronjob.delete

Status

The cronjob status enum: pending · deploying · running · failed · deleting · deleted · updating · paused.

Run now

A manual run-now creates a cronjob_executions row with status: queued and a deterministic Kubernetes job name of the form <cronjob>-manual-<ts>, and returns an executionUuid you can use to follow the run:

{
  "success": true,
  "data": {
    "executionUuid": "8f3c…",
    "status": "queued"
  }
}

Executions and logs

Every run — scheduled or manual — is a cronjob_executions record:

Field	Meaning
executionUuid	Stable id for the run.
status	queued | running | succeeded | failed.
startedAt / completedAt	Run timing.
exitCode	Process exit code.
errorMessage	Failure detail, if any.

Captured logs are read by executionUuid. Log access is ownership-gated through the parent cronjob’s organization, so a UUID cannot be used to probe another tenant’s runs.

Run rollups

The cronjob itself carries aggregate run statistics: totalRuns, successfulRuns, failedRuns, lastRunAt, and nextRunAt.

Environment and secrets

Environment variables ride the deploy queue as plaintext and are returned in responses; secrets are stored encrypted and are never returned. This mirrors how projects handle environment variables and secrets.

Related

• Scheduled functions — the lighter, function-based scheduling option.
• Cronjobs API reference — every endpoint with request/response schemas.
• Plans & limits — which plans include cronjobs.