Configuration as code
Keep your queues and cron jobs in a file next to your code.
Declare queues, schedules and workflows in a workly.yaml, review changes in
pull requests, and apply them with one command. See exactly what will change before it does, and deploy the file
with your app.
One file for queues, schedules and workflows.
A queue or schedule's settings are the same fields as in the API, with the same names, defaults and limits, so there is nothing new to learn. Values can come from environment variables, which keeps one file working across environments and secrets out of the repository.
- Queues: retries, backoff, timeout, rate and concurrency limits.
- Schedules: cron, timezone, the request, overlap and missed-run policy.
- Workflows: their steps, dependencies and deadline.
version: 1
queues:
stock-prices:
max_concurrency: 10
rate_per_second: 2 # the price API allows 120 calls a minute
max_attempts: 3
financial-data:
max_concurrency: 5
timeout_seconds: 120
schedules:
daily-stock-prices:
cron: "0 22 * * 1-5"
timezone: Europe/Stockholm
url: ${API_URL}/jobs/start-price-update # from the environment
refresh-financial-data:
cron: "0 6 * * *"
timezone: Europe/Stockholm
url: ${API_URL}/jobs/refresh-financial-dataValidate, plan, deploy.
workly validate- Checks the file without contacting a server: field names and types, cron expressions, timezones, URLs, and that every ${NAME} is set. It runs the server's own validation, so a file that passes is one the server accepts.
workly plan- Shows what a deploy would create, update and, with prune: true, delete, setting by setting, and changes nothing.
workly deploy- Shows the plan, asks, and applies it. --yes skips the question in CI. Running it again changes nothing.
$ workly plan
Plan for workly.yaml on https://api.workly.run:
+ create queue stock-prices
~ update queue financial-data
max_concurrency: 3 → 5
timeout_seconds: 30 → 120
+ create schedule daily-stock-prices
~ update schedule refresh-financial-data
cron: 0 5 * * * → 0 6 * * *
2 to create, 2 to update, 0 unchanged.What a deploy changes, and what it doesn't.
The file is the truth
Settings work like the API's PUT: a setting left out gets its default, not whatever it was before. A change made in the dashboard to something the file declares is undone by the next deploy.
Secrets stay out of the repo
${NAME} is replaced with an environment variable, and one that isn't set is an error, not an empty string. The plan never shows header values or bodies, only that they changed.
Deletes only when told to
By default, a queue or schedule the file doesn't declare is left alone, and the plan lists the schedules and workflows the file doesn't have. With prune: true, the file is the whole truth: deploy deletes what it leaves out, but never a queue that still has tasks to deliver.
Never undoes an incident
A deploy never pauses or resumes. A queue you paused at 2 a.m. stays paused through the morning's deploy, and the plan says so.
In order
Workflows are applied before schedules, so a schedule can start a workflow declared in the same file. A run already going keeps the definition it started with.
Safe to repeat
Something that already matches isn't touched. A deploy that fails partway reports what it applied, and running it again finishes the job.
Deploy it with your app.
Add a step to your pipeline and the configuration ships with the code that handles it. Run workly validate in pull requests to catch mistakes before they merge; it needs no server or API key.
- name: Deploy Workly configuration
run: |
curl -fsSL https://raw.githubusercontent.com/worklydev/workly/main/install.sh | sh
workly deploy --yes
env:
WORKLY_URL: https://api.workly.run
WORKLY_API_KEY: ${{ secrets.WORKLY_API_KEY }}
API_URL: https://api.example.com # fills ${API_URL} in workly.yamlQuestions
- Can I keep queues and cron jobs in version control?
- Yes. Declare queues, schedules and workflows in a workly.yaml next to your code, review changes in pull requests, and apply them with workly deploy, from your laptop or in CI. workly plan shows what will change first.
- Is this like Terraform?
- The workflow is the same: validate, plan, apply. It is narrower and needs no state file: workly deploy compares the file with the server each time. And unlike Terraform, it doesn't delete by default: removing something from the file leaves it on the server, unless the file sets prune: true.
- How do I use one file for staging and production?
- Put what differs in environment variables, such as ${API_URL}, and set them per environment. Unquoted values are read again after the replacement, so max_concurrency: ${CONCURRENCY} is a number. For environments that differ by more, keep a file per environment and pick one with --file.
- What if someone changes a setting in the dashboard?
- Changes to things the file declares show up in the next workly plan, and the next deploy sets them back to what the file says. To change a setting for good, change the file. Pausing is the exception: a deploy never pauses or resumes a queue or schedule.
Try it in five minutes.
workly dev gives you a server and dashboard on your laptop with nothing else to start, and the Python and TypeScript SDKs let your app enqueue to it. Or sign in to hosted Workly and get a workspace and an API key in a minute, free on the Hobby plan.