SpudSuiteHelp Open SpudSuite

Agents

Workflows and the Factory

Workflows can put the Factory to work and react to what it does. A schedule can ask a project to update our docs every morning. A workflow can start a thread, wait for it to finish, and post what it did in Chat. A thread that opens a pull request or asks a question can start a workflow of its own.

Sending the Factory work

Three actions talk to a Factory project; they need runners from version 0.1.20. Like every SpudSuite action, they act as the person the run is for, who needs to be a member of the workspace.

  • spudsuite.factory_send sends a message to a project's orchestrator, or to one of its threads if you give its title in thread. Name the project by its name, such as Potato tracker. The message shows in the project's chat as the workflow's bot, marked App, with a link back to the run. Give it a Bot name, or choose Send as β€Ί The person who started the run to send it as them. It returns the thread, with its id, and a url to open it.
  • spudsuite.factory_start_thread starts a worker thread with a title and a brief, on the project's model or the Model you choose. It gets a page and a ticket like any thread, and returns the thread.
  • spudsuite.factory_thread reads a thread. It returns its state, whether it's done, waiting on someone or failed, its latest message as reply, and the pull requests it has linked as prs.

Waiting for a thread

To wait until a thread has finished, add a wait step with a condition that reads the thread every few minutes:

- id: send
  type: action
  action: spudsuite.factory_send
  with: {project: Potato tracker, text: Update our docs to match this week's changes}
- id: finished
  type: wait
  needs: [send]
  max_wait: 4h
  condition:
    action: spudsuite.factory_thread
    with: {id: "{{ steps.send.output.thread.id }}"}
    check: "{{ result.done }}"
    poll_interval: 2m

A thread is done once it's ready for review, waiting on a person, resolved, stopped or failed. After the wait, steps.finished.output.result holds what factory_thread returned, so {{ steps.finished.output.result.reply }} is the thread's answer.

Writing the result back

Send what a thread did wherever people will see it:

  • spudsuite.post_message posts it in a Chat channel.
  • spudsuite.update_page writes it into a Docs page. How chooses between Replace what's there and Add to the end.
  • spudsuite.create_page writes a new page, and spudsuite.comment_issue and spudsuite.comment_page comment on an issue or page.

Every step's output is there for later steps too, as {{ steps.<id>.output... }}.

Starting workflows from the Factory

A Trigger with connection: spudsuite can start a workflow when a Factory thread:

Event When Also in the event
factory.thread.started the orchestrator, or a workflow, starts a worker thread
factory.thread.finished a thread finishes a turn: ready for review, or waiting on someone reply, its latest message
factory.thread.failed a turn stops with an error error
factory.decision.asked a thread asks people to choose decision, with question, options and recommended
factory.pr.opened a thread links a pull request for the first time pr, with number, href and repo
factory.message.posted a thread posts a message message, with its body

Each event has factory_project (its id and name) and thread (its id, title, role, state, ticket and url). Narrow a trigger with match: project is the project's name, thread a thread's title, role orchestrator or worker, and status the thread's state.

kind: Trigger
metadata: {name: share-new-prs}
spec:
  connection: spudsuite
  event: factory.pr.opened
  match: {project: Potato tracker}
  workflow: announce-pr
  inputs: {link: "{{ event.pr.href }}", thread: "{{ event.thread.title }}"}

A workflow that messages a thread doesn't start its own trigger again when that thread finishes, so a workflow that answers factory.thread.finished by sending more work won't loop.

Something unclear, or out of date? Spud wants to know: tell us from SpudSuite and we'll fix the page.