Examples
- Diagnose Datadog alerts in Slack — when a Datadog monitor fires, the agent investigates with the Datadog MCP and posts the root cause back to the alert’s Slack thread.
- Weekly flaky test fixes — every Monday morning, the agent scans the last week of GitHub Actions runs for flaky tests and opens a PR with an attempted fix for each.
- Nightly bug hunt — every night, the agent reads the last 24 hours of commits, flags the riskiest changes, and opens a PR with fixes for any bugs it finds.
Scheduled tasks
Use a schedule for recurring work like dependency bumps, periodic test runs, code-quality scans, or weekly maintenance passes. Configure:- Environment, branch, and model
- Schedule and task: describe in plain language what the agent should do and when it should run. Niteshift parses it into a task prompt, recurrence rule (RRULE), timezone, and a human-readable schedule label.
Webhook triggers
Use a webhook for event-driven work like CI failures, monitoring alerts, deploy notifications, or anything else that emits an HTTP webhook. Configure:- Name, environment, branch, and model
- Task prompt template: the instructions the agent gets each time a request hits the URL. Use
{{payload.field}}(dot paths into the JSON) or{{payload_json}}/{{payload}}to insert the full request body as pretty-printed JSON.
Authentication
Each trigger has a single shared secret. Incoming requests authenticate with one of:- HMAC (preferred): send
x-niteshift-signatureandx-niteshift-timestampheaders. The signature issha256=<hex>where the HMAC is computed over<timestamp>.<body>using the trigger secret. Includes timestamp-based replay protection. - Bearer token: send
Authorization: Bearer <secret>. Use this for sources like Datadog that can set static custom headers but can’t compute a per-request signature.
Rate limiting
Each webhook URL is limited to 10 requests per rolling minute and 100 per 24 hours. The burst rule runs first; a request only counts toward the daily cap if it would have passed the burst check, so a flood of throttled calls does not use up the whole day.429 responses: JSON with error and retryAfter (seconds), plus the Retry-After and
X-RateLimit-* headers. Header values match whichever limit blocked you; X-RateLimit-Reset is a
Unix time in seconds for the end of that limit’s current window.
Store automations in your repository
You can store each automation in your environment’s primary repository. Niteshift will automatically update the automations when changes are committed to your repository’s default branch. Each automation should go in<settingsDirectory>/automations/<key>.mdx. The settings directory is .niteshift or an environment subdirectory, such as .niteshift/backend.
For example, .niteshift/automations/weekly-review.mdx:
maintenance-bot with your service account handle.
File format reference
The YAML front matter between--- lines holds the fields below. The rest of the file is used
verbatim as the task prompt (1–20,000 characters); braces, JSX, and code are literal text, not
executed as MDX. Unknown front-matter or trigger fields are rejected. Optional execution fields
let you override the task’s model, agent, and sandbox settings; availability depends on your
account and the selected model.
Required front-matter fields
Every file must include these fields, includingschemaVersion: 1.
Optional front-matter fields
Choose an agent, model, and provider
agentis the coding tool that reads the prompt, edits files, and runs commands. For example,claudeselects Claude Code;codexselects Codex.modelis the AI model the coding tool uses.claude-sonnet-latestfollows the latest Sonnet release; a concrete ID such asclaude-sonnet-4-6pins a version.provideris the service or router that handles requests to that model, such asanthropic,openai, oropenrouter. It must support the chosen agent and model and be available to the service account named inrunAs.
Schedule trigger fields
Each schedule entry intriggers has these fields:
Webhook trigger fields
Each webhook entry intriggers has these fields:
For example, replace the schedule’s
triggers list with this to run from a webhook:
Migrate existing automations
In an existing Niteshift task, you can prompt it to export automations. It does so via thens automations export CLI tool, which you can also run within the task terminal.
Example usage:
- Export your selection; add
--target-service-account <handle>for automations that run as a person. - Pause the original UI-managed automations. You can prompt a task to help you do this, or manage it in the UI.
- Review and commit the exported files, merge the change into the default branch, and verify that the newly created automations work.
- Delete the originals once you’ve verified that the new copies work.
Limitations
Repository-stored automations have some limitations that don’t apply to UI-configured automations:- They can’t use Slack triggers.
- They can’t file their tasks into projects.