Schedule or webhook work

This guide sets up a trigger that files a paused work item for you, then verifies it. You need a connected repo (kraft repo connect) and a running Kraft server. The fields and the HTTP contract are in Inbound triggers.

Schedule a work item

1. Add a triggers: entry to $KRAFT_HOME/templates/policy.yaml:

   triggers:
     - cron: "0 9 * * 1,2,3,4,5"  # 9:00 UTC on weekdays
       repo: /path/to/repo
       chain: default
       title: "Weekday dependency check"
       description: "Filed by the 9am weekday trigger"
   

2. Reload the policy, or add the entry through Settings instead:

   kraft admin reload
   

Kraft evaluates the schedule in UTC. The next matching minute files the item.

File a work item from a webhook

Post to /api/triggers from anything that can fire a webhook, such as CI or a script.

While Kraft is bound to 127.0.0.1 (the default), a call from the same machine needs no login:

curl -s -X POST http://127.0.0.1:8765/api/triggers \
  -H 'Content-Type: application/json' \
  -d '{"title": "Dependency check", "repo": "/path/to/repo", "chain_template": "default"}'

After a non-loopback bind, every call needs the trigger token from $KRAFT_HOME/run/trigger-token, including one from the same machine, which otherwise gets 401. From another machine, also use the address you reach Kraft at. See Remote access.

curl -s -X POST https://<your-tunnel-hostname>/api/triggers \
  -H "Authorization: Bearer $(cat ~/.kraft/run/trigger-token)" \
  -H 'Content-Type: application/json' \
  -d '{"title": "Dependency check", "repo": "/path/to/repo"}'

Kraft answers 201 with the new work item, filed paused.

The trigger token is good for POST /api/triggers only, so it is the one to store as a CI secret or give a webhook sender. Do not use run/mcp-token there: it is a full-admin credential. See The bearer token for how to rotate either.

Verify

List the paused items and look for the new one:

kraft view list --status=paused

The item shows as Not started. Start it from the board when you are ready. For a cron trigger, wait for the next matching UTC minute first. If nothing appears, check the server log for a skipped-trigger warning, which names the unconnected repo or unknown chain.

Related

• Inbound triggers: the fields and status codes.
• Remote access: reach the server from another machine.