Step 9 - Scheduling
hivel-agent has no built-in scheduler - use your own cron / systemd timer. sync and work-metrics are independent commands with different recommended cadences; run them as separate cron entries.
Add this to the crontab on the same machine where you installed the agent.
sync - once daily
# crontab - daily at midnight UTC
0 0 * * * cd /opt/hivel-agent && ./hivel-agent --config config.yml --env-file .env sync
--no-progress >> /var/log/hivel-agent.log 2>&1The agent does not need to run more often - each run only pulls incremental changes since the last sync.
work-metrics - hourly (Bitbucket / Azure DevOps / GitHub / GitLab only)
Only needed if you're using the work-metrics classification job. Its default --time-budget is 50 minutes specifically so one run finishes before the next hourly run starts - schedule it accordingly:
# crontab - every hour, at 15 minutes past
15 * * * * cd /opt/hivel-agent && ./hivel-agent --config config.yml --env-file .env work-metrics
>> /var/log/hivel-agent-work-metrics.log 2>&1If you lower --time-budget below 50 minutes, you can schedule more frequently than hourly; if you raise it, widen the interval to match so runs don't overlap.
Checking agent status & logs
hivel-agent is not a long-running daemon - each sync or work-metrics invocation runs once and exits. "Is it running" splits into a few different real questions:
Is a run in progress right now?
pgrep -f hivel-agentNo output means nothing is currently executing.
Did the last scheduled run succeed? For sync/work-metrics run via cron with no --output-dir (the normal case, as in the examples above), the agent writes its full structured log to both stdout and a fresh temp directory on every run - that temp path isn't printed anywhere, so it's not practically discoverable after the fact. The reliable way to check what happened is the log file your own cron redirect writes to:
This is exactly why the cron examples above redirect stdout/stderr to a fixed file - set that up before you rely on cron for anything unattended.
Structured `status.json` / `summary.json` / `diagnostics.json` (see Files generated per run) only land somewhere durable and inspectable if you pass --output-dir - sync is the one command here that doesn't accept that flag (work-metrics does, via --output-dir, download-only mode). If you're running plain sync on a schedule and need persistent structured status rather than a log stream, use the download → review → send workflow instead.
Is the schedule itself actually firing?
Last updated