Skip to main content

Routines

Version: 2.0 | Last updated: 2026-09-01

A routine runs a Bluebox agent automatically, on a schedule or from a matching GitHub event. When it fires, it starts an agent run exactly as if you had asked the question yourself: a nightly cost review, a Monday-morning SLO check, a review posted the moment a pull request opens.

Open Routines from the sidebar to see the routines in your workspace.

Create a routine​

Select Create routine. Only one field is required:

  • Name — a short label, shown in the routines list and in run history. For example, Nightly cost review.

A routine starts on a schedule by default. Switch Trigger to GitHub event to fire it from repository activity instead, as described in Choose a trigger below.

Schedule starts on Daily at 6:00, so a routine is ready to save as soon as you have named it. Change the cadence if you want a different one.

Add a Prompt to say what the agent should do each time it fires, written the same way you would type it in chat, for example Check for cost anomalies and summarize findings. Leave it blank and the name is used as the prompt, so give the routine a descriptive name if you skip this.

Everything else is optional. Select Create routine to save.

Choose a trigger​

Every routine starts from exactly one trigger: a schedule, or a GitHub event delivered to your workspace. Pick the trigger when you create the routine; it cannot change afterward, so create a new routine to switch from one to the other.

Run on a schedule​

The Schedule control offers five presets and a custom option, and starts on Daily:

  • Once — fires a single time at a date and time you pick, then stops.
  • Hourly — every hour, on the hour.
  • Daily — every day at a time you pick. This is the default.
  • Weekdays — Monday through Friday at a time you pick.
  • Weekly — one day a week at a time you pick.
  • Custom — a five-field cron expression (minute hour day-of-month month day-of-week). Use this for cadences the presets don't cover, such as 0 9 1 * * for 9 am on the first of every month.

Recurring routines also take a Timezone, which defaults to your browser's. The schedule is interpreted in that timezone, so a daily 9 am routine stays at 9 am local time across daylight-saving changes. You will find it under Advanced.

A routine's schedule type is fixed once created: a Once routine cannot become recurring, or the reverse. Create a new routine instead.

Run on a GitHub event​

A GitHub event trigger fires the routine when a matching webhook delivery arrives for your workspace, instead of on a schedule. It requires a GitHub connection, set up during onboarding. If none exists yet, the GitHub event option is disabled with a hint to connect one in Settings.

Configure four things:

  • Event — the kind of GitHub activity to watch: Pull request, Issue, or Comment. A routine watches one event; create a separate routine to react to a different one.
  • Actions — which actions of that event fire the routine. At least one is required, and the routine fires when any selected action occurs.
  • Repositories — optional. Limits the trigger to specific repositories connected to your workspace. Leave it empty to fire for any connected repository.
  • Filters — optional conditions that narrow which deliveries fire the routine, covered below.

The actions available depend on the event:

EventActions
Pull requestOpened, Labeled, Closed, Ready for review, Synchronized, Reopened, Edited, Converted to draft, Review requested
IssueOpened, Assigned, Labeled, Closed, Reopened, Edited
CommentCreated

If you leave both Repositories and Filters empty, the routine fires for every matching event across the workspace, which can use up your run limit quickly. Scope the trigger to specific repositories or add a filter to keep it targeted. See Runs count toward your workspace limits.

Narrow the trigger with filters​

Add up to 20 filter rows, each comparing one field of the delivery against a value. Every row must match for the routine to fire.

FieldApplies toNotes
AuthorPull request, Issue, CommentThe pull request, issue, or comment author's login, not whoever triggered the delivery.
TitlePull request, Issue, CommentFor a comment, the title of the issue or pull request it was posted on.
BodyPull request, Issue, CommentFor a comment, the comment body.
LabelsPull request, IssueMatches if any label on the item satisfies the filter.
Base branchPull request
Head branchPull request
Is draftPull requestValue is true or false.
Is mergedPull requestValue is true or false.

Each row picks an operator: equals, contains, starts with, is one of, is not one of, or matches regex. Text comparisons are case-insensitive except matches regex, which searches for a match anywhere in the value using RE2 syntax (add (?i) for a case-insensitive pattern, or anchor with ^ and $ to require a match of the entire value). Is draft and Is merged support equals only.

Filter out bots and apps. GitHub bot and app accounts have a login ending in [bot], for example dependabot[bot]. To exclude one specific bot, add an Author filter with is not one of and its login. To exclude any bot, use Author with matches regex and the pattern \[bot\]$.

When the routine fires, the agent receives the delivery's details, including the repository, the pull request or issue number, and the event type and action, the same way it receives a prompt for a manual run.

Limit when a routine runs​

Start at, End at, Max occurrences, Overlap policy, and Timezone sit under Advanced, collapsed. Every one is optional and already has a sensible default, so most routines never need them. Open the section to set them. When you edit a routine that already uses one, the section is open so you can see the value.

Three optional fields bound a routine's lifetime:

  • Start at — the routine does not fire before this date. Leave blank to start immediately. Recurring routines only.
  • End at — no new runs fire after this date. Leave blank to run indefinitely.
  • Max occurrences — stops the routine after this many runs. Leave blank for no limit.

Once a routine passes its end date or reaches its run limit, it stops for good and its last outcome reads Expired or Limit reached. Pushing the end date out or raising the limit does not bring it back on its own, and neither does the Enabled toggle. To restart it, edit its schedule or timezone (that recomputes the next run), or create a new routine.

You can raise or lower Max occurrences later, but you cannot clear it entirely once set. To remove the cap, delete the routine and create it again.

Decide what happens when runs overlap​

A run can still be going when the next one is due, say an hourly routine whose work takes 70 minutes. Overlap policy, under Advanced, decides what happens then:

  • Skip (the default) — the new fire is skipped and the in-progress run continues. The skip is recorded, not silent.
  • Allow — the new run starts anyway, and both run at the same time.

This applies to recurring routines only. A GitHub event routine always behaves like Allow: since each webhook delivery is independent, there's no schedule slot for it to overlap with. Each new matching delivery is evaluated on its own, and starts a run unless it's a redelivery of one already handled, or the routine has since expired, hit its occurrence limit, or is throttled.

Run a routine now​

Select Run now (on the routine's detail page, or as a row action in the list) to start a run immediately, without waiting for the next scheduled time or the next matching GitHub event. This is the fastest way to check that a prompt does what you expect before you leave a routine running.

A manual run is deliberately independent of the schedule. It does not change when the routine next fires, does not count toward Max occurrences, and ignores the overlap policy. It also works on a disabled routine, so you can test one before turning it on.

Turn a routine on or off​

The Enabled toggle on the routines list is the master switch. A disabled routine never fires, whatever else it is configured to do. Turning it off does not stop a run already in progress and does not delete anything.

Turning it back on resumes the schedule from where it left off, which is not always the next slot on the calendar. If a scheduled time passed while the routine was off, expect a run shortly after you re-enable it. If it was off for longer than one interval, it skips the backlog and waits for the next slot.

Use the toggle rather than deleting a routine you expect to want again.

Edit or delete a routine​

Open a routine from the list, then select Edit to change any field except its trigger type, or Delete routine to remove it. Both actions are also available as row actions in the list.

For a GitHub event routine, editing can change the event, actions, repositories, and filters. Only the trigger type itself, schedule versus GitHub event, is fixed once the routine is created.

Deleting a routine is permanent. Runs it already started are unaffected: any run still in progress continues to completion, and their results stay available. What you lose is the routine's own history view of them.

Read the run history​

The routines list carries a Next run and a Last run column, so you can see at a glance whether a routine is doing what you expect. Both show the time as an offset from now (in 19h, 5h ago), and anything further out than a week keeps its date instead. Point at either to read the exact timestamp. Last run pairs the time with a colored icon for the outcome, and covers the most recent time the routine was due, including the times it did not run.

Cadence names a timezone only when it differs from your own. A routine that fires at 06:00 in your timezone reads At 06:00 AM; one that fires at 06:00 somewhere else reads At 06:00 AM · America/New_York, so a time that is not yours is never mistaken for one that is. The full cadence, timezone included, is always on the routine's detail page.

Open a routine for the detail: its cadence in plain language, when it runs next, and Run history (the runs it has actually started, newest first, with each run's status and a link to its full result). Select Load more to page further back. Skipped fires start no run, so they never appear in the history; the list's Last run column is where you see them.

What each outcome means​

OutcomeMeaning
Run startedThe routine fired and started a run.
Skipped (overlap)The previous run was still going and the overlap policy is Skip.
Skipped (stale)More than one scheduled time went by before Bluebox reached the routine, so it skipped ahead to the next slot.
Skipped (throttled)Your workspace has reached its limit on new runs.
Skipped (not available)Routines were temporarily unavailable for your workspace when this routine was due. The routine is not disabled; it picks up at a later time. For one-time routines, the run time shifts forward while Routines is unavailable.
ExpiredThe end date passed. The routine has stopped for good.
Limit reachedThe routine hit Max occurrences. It has stopped for good.

A routine that misses its scheduled time by a little still runs, late, as soon as Bluebox reaches it. What it will not do is work through a backlog: if more than one scheduled time has passed, it abandons the missed ones, records Skipped (stale), and picks up at the next slot. A daily routine that misses a full day runs once tomorrow, not twice.

A GitHub event routine only ever records Run started, Skipped (throttled), Expired, or Limit reached. Skipped (overlap), Skipped (stale), and Skipped (not available) describe schedule slots and never appear for it: each webhook delivery is evaluated on its own, and a redelivery of one already handled is silently deduplicated rather than recorded as a skip.

Who can see your routines​

New routines are shared with your workspace by default. A routine is automation the whole team relies on, so your colleagues can see what is scheduled and read its results rather than wondering why something ran overnight.

Sharing is read-only. Everyone in the workspace can open a shared routine, read its schedule and prompt, and see its run history. Only you, as its owner, can edit it, run it now, turn it off, delete it, or change who sees it. A workspace owner can do those things to any routine, and that access is recorded.

You choose the visibility for each routine with the Visibility control in the create and edit form:

  • Only me — only you and the workspace owner see the routine.
  • Workspace — everyone in your workspace can view its schedule, prompt, and run history. This is the default.

The routines list has a Mine / Shared with me / All filter, so you can narrow a busy workspace to just your own routines. A small icon beside each name says whether the routine is private or shared, and an Owner column names who scheduled it. Under Mine that column is hidden, since every routine there is yours.

A routine's runs inherit its visibility. If a routine is shared, the runs it starts are readable by the workspace too; if it is private, so are its runs.

Workspace owners can change the default for new routines under Settings → Users & sharing. Changing the default does not touch routines that already exist; those keep the visibility they have until their owner changes it.

If someone is removed from a workspace, the routines they scheduled there are turned off. They stay off until a workspace owner turns them back on.

Runs count toward your workspace limits​

Every run a routine starts, whether scheduled, GitHub event, or manual, counts against your workspace's allowance for new runs, the same as an investigation or a chat you start yourself. A routine firing every hour uses that allowance 24 times a day, and an unscoped GitHub event trigger can use it up far faster if the matching event is common.

If the workspace is at its limit when a routine is due, the fire is skipped and recorded as Skipped (throttled). The routine is not disabled; it fires again on its next slot, or the next matching event, once there is room.

Next steps​