Workflows

Edit a workflow

Open Workflows and select the workflow you want to change. Use Canvas to work with its steps, or YAML to edit the same definition as text.

On the canvas:

• Select a step to edit its settings.
• Use the add-step buttons to insert work at that point in the sequence.
• Select Starts when to inspect triggers and declare inputs.
• Select the workflow settings node to choose its execution identity, container profile, repository mode and instructions.

Edits are saved as a draft. They don't change the published workflow until you choose Publish. Check any validation errors shown beside Publish before continuing.

To create a workflow, use New workflow at the top of the page. Give it an ID in its YAML definition, configure its steps and publish it before running it.

Choose where it runs

The workflow's settings determine its execution environment:

• Runs as selects an active agent identity from your organisation.
• Container profile selects the environment used for the run.
• Works on: Repository requires a repository and prepares its worktree.
• Works on: If given uses a repository when the run supplies one.
• Works on: None uses a scratch workspace without cloning a repository.

Choose the repository mode to match the work. A workflow that only processes an incoming event can use a scratch workspace; one that changes repository files needs a repository. Archie validates whether the selected steps support the mode you've chosen.

Declare inputs and outputs

In Starts when, declare the inputs the workflow needs. Give each input a name and type, and mark it required when the run can't proceed without it.

A manual run supplies these values in its run form. An event binding supplies them from mapped event fields or constants. For example, an input named summary can receive a message extracted from an alert payload.

Declare structured outputs in the workflow settings when a caller needs results from the run. Outputs are returned through capture tools, so the selected container profile must support them. These capture tools collect workflow results; the Events page's Capture step receives incoming webhooks.

Test an edit

When you've changed an existing workflow, its Run button becomes Test. Test runs the draft once without publishing it. Supply the requested inputs and repository in the dialog, then follow the run on the canvas.

Test runs skip forge writes and pushes, including those in workflows they call. Commands and tools still execute, so a test can still affect external systems through those commands and tools.

When you're satisfied with the result, choose Publish. Each run keeps the workflow definition assigned to it, so publishing an edit doesn't replace the definition of a run already using an earlier version.

Start work automatically

Select Starts when to see what can launch the workflow. The list can include event bindings, built-in issue routes, playbooks and other workflows that call it.

Choose Bind an event to connect a source and example event to the workflow's inputs. Save the binding, then approve it before expecting events to start runs. The Events guide covers Capture, Map and Bind in detail.

The enabled switch controls whether the published workflow runs on events. Use it to stop automatic launches while you're changing an integration. Built-in issue routes are shown as Built-in; they aren't event bindings you can remove from the Bind list.

Inspect a run

Use the run selector above the canvas to follow a specific run. Select a step to inspect its execution details, or choose Open run from More to open the task.

Runs lists the workflow's tasks and their statuses. Performance shows stage timings and failures once runs have produced that data. On narrower screens, these views are in More.

Restore a version

Open History and select a revision to compare it with the current definition in YAML or on the canvas.

Restore this version loads that revision into the draft. Review it and choose Publish to make it active. Restoring a revision doesn't publish it automatically.