How outside events reach a task

Much of the work a task stands for happens outside Spotlight. A pull request is reviewed on GitHub, a check fails in CI, someone replies in a Slack thread. Spotlight hears about each of these and applies it to the right task.

One event, start to finishCopy Anchor Link

Say a task on the Delivery line reached Code Review, and Code Review opened a pull request for it. A reviewer then comments on that pull request. GitHub tells Spotlight by sending it a webhook, a request that describes the comment. Spotlight checks that the webhook came from GitHub, and turns it into its own short account of the event, which it calls a happening. This one is named github.pull_request.commented. Spotlight then finds the task the happening is about, the one that opened the pull request, and applies the Delivery line's rule for it: a comment sends the task to Code Review. The task is already there, so it stays, and a new Code Review run starts with the comment among its notes.

Checking where the event came fromCopy Anchor Link

Spotlight connects to each outside service through an integration. GitHub's is built in. A team adds others, such as Slack or an issue tracker, as integration resources.

The integration checks every webhook, and there is no way to switch that off. Agents act on what an event says, so a forged one could feed an agent words nobody sent.

When Spotlight comments on a pull request or posts a question in Slack, the service sends that post back as an event, and Spotlight should not react to its own words. GitHub's integration ignores comments and reviews from bot accounts, Spotlight's own included. Another integration drops Spotlight's posts when it says how to recognise them.

Finding the taskCopy Anchor Link

A task keeps a record of the things outside Spotlight that belong to it, such as the pull request it opened or the Slack thread it started in. Spotlight calls each of these a mark. When the task in the example opened its pull request, Spotlight noted that pull request on the task. The comment names the same pull request, so Spotlight finds the task by it. Only one task can hold a given mark.

Events about a branch need no mark. Spotlight names the branch it works a task on after the task, so a failed check on that branch finds the task directly.

Some things an event carries are too broad to find a task by. A Slack message names its channel, but a team opens many tasks from one channel. An integration can still keep the channel on the task, for example to know where to post a question, without ever using it to find one.

When no task is foundCopy Anchor Link

If no task holds what the event is about, the integration may open a new one. A Slack message that mentions Spotlight is the usual case. Each line has a role, a word for the kind of work it takes, such as delivery. The integration names a role, and the task opens on the team's line with that role. Otherwise the event is ignored.

Requests to review a pull request go instead to a line with a review policy, such as Review, and the policy decides whether to take them; see Have Spotlight review pull requests.

What the event does to the taskCopy Anchor Link

A line's rules for events, which Spotlight calls reactions, decide what an event does, and each moves the task to a station. Delivery's include:

• a failed check moves the task to Implementation
• a comment or a request for changes on the pull request moves it to Code Review
• a merged pull request moves it to Completed

Built-in lines lists them all. When no run holds the task, a rule moves it at once, and if the station it moves to has an agent, a new run starts there with the event among the task's notes.

While a run holds the task, working on it, waiting to start, or paused until a person answers it, a rule does not move it. The event is added to the task's notes, where the agent sees it, and the move waits. If the run passes the task on to a station, the task goes there and the waiting move is dropped. If the run ends any other way, by finishing, asking a person, failing or being stopped, the waiting move applies then. When several are waiting, the latest one applies, and a person moving the task first drops them.

While a run holds the task, an event that would move it to Completed, such as a merged pull request, goes differently. The work it was about is settled, so it stops the run at once, keeps the task at its station, and asks the task's assignee whether to close the task or carry on. If the task is already waiting on a person's answer to a question the run asked, it asks nothing new: it adds a note to the open question and leaves the paused run as it is.

A few cases go differently:

• If the task is already at the station the rule names, it stays there, and the event is added to its notes. A new run starts at that station if the station has an agent, unless a run is already working on the task or the task is waiting for an answer.
• If the task is waiting for someone's answer and the event is a reply, such as a reply in the task's Slack thread, the reply answers the question, even when the line has no rule for it, and the agent carries on as if it had been answered in the inbox. A rule that moves the task elsewhere comes first, and while a run holds the task that move waits like any other.
• Otherwise, if the line has no rule for the event, or the task is already completed, nothing happens.

Repeated events and loopsCopy Anchor Link

Services send the same webhook again when they are unsure it arrived. Spotlight acts on each event once, so one merge can't move a task twice. Hooks, which call a team's own services when something happens, can set off events that set off more hooks; Spotlight stops such loops, with the limits given in the spotlight_hook reference.

GitHub events lists every GitHub happening and mark, and Open tasks from Slack and post questions back sets up the Slack case.