Jobs and Deploy Hooks
An app serves requests; a job is finite work that belongs to the app: a nightly report, a cache rebuild, a backup, a database migration that must run before a new version takes traffic, or an operator one-off like a reindex. Every run is recorded, with its status and its output available while the run’s container exists.
A job has one executor and one trigger. Executors:
- Command: runs in a fresh container from the app’s deployed image (or from another image).
- Starlark function: called inside OpenRun, with the app’s params, secrets and service binding credentials.
Triggers:
| Trigger | Started by |
|---|---|
manual | The default. Started from the CLI, the console or through API |
cron | A schedule run by the OpenRun server, on the app’s prod and stage instances |
before_deploy | A deploy gate: runs before a new version of the app is written, from the image just built and against the instance being deployed to. A failing gate stops the deploy |
Every job, whatever its trigger, can also be run manually.
Declaring jobs in app.star
Jobs are declared with ace.job and passed to ace.app in jobs=:
load("container.in", "container")
load("proxy.in", "proxy")
def report_region(dry_run, args):
return ace.result("Configured region: " + args.region)
app = ace.app("orders",
routes=[ace.proxy("/", proxy.config(container.URL))],
container=container.config(container.AUTO, port=8000),
jobs=[
ace.job("migrate", command=["python", "manage.py", "migrate", "--noinput"],
trigger=ace.before_deploy(), timeout="10m"),
ace.job("nightly-report", command=["python", "manage.py", "send_report"],
trigger=ace.cron("0 3 * * *", timezone="America/Los_Angeles"),
timeout="1h", params=["region"], description="Emails the daily orders summary"),
ace.job("db-backup", image="image:postgres:16", inherit_env=True, shell=True,
command=['pg_dump --dbname="$POSTGRES_URL" --format=custom --file=/backup/$(date +%F).dump'],
trigger=ace.cron("@daily"), volumes=["backup:/backup"]),
ace.job("report-region", run=report_region, trigger=ace.cron("@hourly"), params=["region"]),
],
permissions=[
ace.permission("proxy.in", "config", [container.URL]),
ace.permission("container.in", "config", [container.AUTO]),
])The example assumes an app image containing manage.py and the named management commands, plus a PostgreSQL binding providing POSTGRES_URL. Define the parameter used by the jobs in params.star:
param("region", default="us", description="Report region")The db-backup job uses a local named volume on Docker/Podman. Copy those backups off the host separately. Using pg_dump directly preserves its exit status so a failed dump fails the job.
Job fields
ace.job(name, command=[], args=[], shell=False, image="", run=None, env={}, inherit_env=None, volumes=[], options={}, trigger=ace.manual(), timeout="1h", enabled=True, params=[], description=""):
| Field | Default | Meaning |
|---|---|---|
name | Lower case letters, digits and dashes, up to 20 characters, starting with a letter or digit; unique across the app’s jobs and sidecars | |
command, args | [] | The command line, run in place of the image entrypoint. shell=True runs it through sh -c |
image | the app’s own image | image:<ref> (or a bare reference) to run another image. Foreign images must be allowed by the security.allowed_job_images server config (exact references or regex: entries; the default ["*"] allows any image) |
run | None | A Starlark function fn(dry_run, args) with the action handler shape, called in the OpenRun process instead of running a container. dry_run is always False; args carries the params.star values with the run arguments applied. Use run for Starlark apps, and for anything that touches an app’s SQLite data: a job container must never open the database of a running app. Only app.star can declare run jobs |
env | {} | The job’s own env |
inherit_env | True for app image jobs, False for foreign images | Copies the app env (params, binding env vars, CL_APP_PATH, CL_APP_URL) into the job container first. Foreign images get no credentials unless asked (a backup job must ask) |
volumes | [] | Docker/Podman only: named volumes, name:/path. A named volume also used by the app is the same volume. The managed SQLite volume cannot be mounted by a job |
options | the app’s container options | Container options for the job, same keys as --copt |
trigger | ace.manual() | ace.manual(), ace.cron(schedule, timezone="UTC") or ace.before_deploy(). The schedule is a five field cron expression or a descriptor like @daily or @hourly, in the given IANA timezone. Interval schedules (@every) are not supported; use an expression like */15 * * * * |
timeout | "1h" | A Go duration; the run is killed at the deadline and recorded as timed_out |
enabled | True | A disabled job keeps its history and is never scheduled or gated; openrun job run --force still runs it |
params | [] | The params.star params a manual run may set with --arg name=value; values are checked against the param type. A command job receives every declared param as a CL_JOB_ARG_<NAME> env var (the argument when given, the app’s configured param value otherwise); a run job gets them as args.<name>, typed by the param definition |
description | "" | Free-text description of the job |
The job definitions are part of the app version: they are stored when the app loads, and openrun job list reads them from the app metadata.
Job containers
A command job runs in a new container from the image the app instance last deployed: the built image, or for image: apps the upstream image at the digest recorded by the last reload, so a moved tag does not change what a job runs. job run on an app that has never been deployed fails with “deploy the app first”. The container gets the app env when inherit_env is set, the job’s env, and:
| Env var | Value |
|---|---|
CL_APP_STAGE | prod, stage, preview or dev |
CL_APP_VERSION | the app version |
CL_JOB_NAME, CL_JOB_RUN_ID | the job and run identity, for logs and idempotency keys |
CL_JOB_TRIGGER | manual, cron or before_deploy |
CL_JOB_SCHEDULED_AT | the intended cron tick (RFC 3339), cron runs only |
CL_DEPLOY_REASON, CL_PREVIOUS_VERSION | deploy gates only: reload, apply, create or promote, and the version being replaced |
CL_JOB_ARG_<NAME> | the run arguments |
- Success: exit code 0 is success.
PORTis not set and no health check runs. - Runtime: on Docker/Podman the run is a labeled container; on Kubernetes it is a
batch/v1 Jobin the apps namespace withrestartPolicy: Neverand no service account token. - Retention: the container is left in place when it exits so its output can be read with
openrun job logs. It is removed when its run record is retired by retention (jobs.retain_runsin[app_config], default 50 runs per job, overridable per app withopenrun app update conf jobs.retain_runs=N). - Output: read from the container runtime and not copied or redacted. A job that prints a credential shows it to anyone with
app:read_detailon the app.
Scheduled runs
- Ticks: the server checks the cron jobs of every prod and stage app once a minute, on the leader. A tick starts a run unless the job already has an active run, in which case the tick is skipped. There are no retries, and ticks that pass while no server is running are not replayed.
- Stage: stage schedules run against the stage instance and its staging binding accounts, so a staged job change is exercised before it is promoted. Preview and dev apps run no schedules. A job that must not run on stage can check
CL_APP_STAGEand exit. - Node failure: a run executes on the node that started it. If that node stops, the run is marked
lostafter a minute and can be started again by hand. Jobs should therefore be idempotent.
Deploy gates
A before_deploy job runs when a new version deploys to an app instance:
| Operation | Where the gate runs |
|---|---|
app reload, apply, sync runs | On the stage instance, before the reload transaction opens, from the image just built |
app promote | On the prod instance, from the stage code, with the prod binding accounts |
--promote on a reload or apply | The stage gate and then the prod gate run before the operation writes anything |
app create | On the stage instance before the create transaction opens, so a failure stops the create before anything is written. When the gate needs a binding the same operation creates (an auto binding, or a binding declared in the same apply file), it runs inside the create instead and a failure rolls the create back |
openrun version switch, metadata-only updates like param update --promote | No gates |
- Order: gates run in declaration order, and the first failure stops the operation with the run id and the tail of its output.
- Dry runs skip gates: they have real side effects.
- Backward compatibility: the previous version keeps serving during a gate, so migrations must be backward compatible with it (expand/contract).
- Preview and dev apps run no gates; a gate job can still be run manually on them.
Declaring jobs in apps.ace and on the CLI
The same fields are accepted as job(...) calls, dict literals or JSON strings in apps.ace, on app create --job and with app update jobs. Operator-set jobs replace a same-name job of the app definition whole, and add new ones; run jobs can only come from app.star.
backup = job("db-backup", image="image:postgres:16", inherit_env=True, shell=True,
command=['pg_dump --dbname="$POSTGRES_URL" --format=custom --file=/backup/$(date +%F).dump'],
trigger=cron("0 2 * * *"), volumes=["backup:/backup"], timeout="30m")
app("/orders", "github.com/acme/orders", spec="container", bindings=["/db/orders"],
sidecars=[sidecar("cache", image="image:memcached:1.6-alpine", port=11211)],
jobs=[
job("migrate", command=["python", "manage.py", "migrate", "--noinput", "--database", "primary"],
trigger=before_deploy(), timeout="20m"),
backup,
])
# the same job attached to several apps
for p in ["/billing", "/inventory"]:
app(p, "github.com/acme" + p, spec="container", bindings=["/db" + p], jobs=[backup])openrun app create --spec container --bind /db/orders \
--job '{"name":"nightly-report","command":["python","manage.py","send_report"],"trigger":{"type":"cron","schedule":"0 3 * * *","timezone":"UTC"}}' \
github.com/acme/orders /orders
# Replace the metadata jobs (staged, promote to apply to prod); "-" clears them
openrun app update jobs --promote @jobs.json /ordersThe JSON trigger forms are {"type": "manual"}, {"type": "before_deploy"} and {"type": "cron", "schedule": "0 3 * * *", "timezone": "UTC"}. --job and app update jobs accept a JSON object, or @file holding an object or a list.
Running and inspecting jobs
openrun job list [appPathGlob] # jobs, next scheduled run and last status; a staged job change shows as a stage row
openrun job run nightly-report /orders # start on prod, returns the run id
openrun job run --stage --wait migrate /orders # run on stage and wait for the result
openrun job run --arg region=eu nightly-report /orders # run arguments for the job's params
openrun job run --force report-region /orders # run a disabled job, or alongside an active run
openrun job runs [--job name] [--status failed] /orders # run history of the prod and stage instances
openrun job logs <run-id> # output, while the run's container exists
openrun job cancel <run-id> # stop an active run (on the node executing it)- Run statuses:
running,succeeded,failed,timed_out,canceledandlost. - Timestamps: every job timestamp is UTC. Schedules evaluate in the job’s
timezone(default UTC); run times,CL_JOB_SCHEDULED_ATand the CLI output are RFC 3339 UTC. - APIs: the same operations are available as REST APIs (
/_openrun/jobs,/_openrun/jobs/run,/_openrun/jobs/runs,/_openrun/jobs/logs,/_openrun/jobs/cancel) and as MCP tools. - Audit: every finished run writes a
jobaudit event with the run id and status.
Permissions:
| Operation | Permission |
|---|---|
| List jobs | app:read on the app. Without app:read_detail the listing is the basic view: name, trigger, enabled, timeout and the last run’s status, with the command, env, run definition and arguments blanked |
| Run history and logs | app:read_detail |
| Run and cancel | app:update |