Forge Workflows (@forge/workflows) is under development and is not yet available. These pages describe the
planned API, which may change before release.
For more details, see Forge EAP, Preview, and GA.
Forge Workflows lets you write a multi-step background job as one chain of TypeScript calls. For example, you can send 200 issues to an LLM, wait for every result, and post a summary.
You could build that job from async events yourself, but you'd have to save state between events, work out when every item has finished, retry failures, and track progress. Workflows does this for you. It passes each step's result to the next step, waits for a fan-out to finish, retries failed steps, can wait for days for a person to respond, and gives you a run ID to check on the run.
Workflows uses five ideas:
task()..pipe(), .catch() and .loop(). Each step receives
the value from the step before it..start() sends the chain off to run as a workflow run, and gives you a run ID. Use runs.get(runId) to
check on the run and read its result.Workflows runs on Forge async events: each task call is sent as an async event to a new invocation of your app. That's why runs count toward your app's async events limits, and why a step can occasionally run twice.
This workflow summarises an issue and posts the summary as a comment. summariseIssue and addComment are your own
functions, for example ones that call the Forge LLMs API and
the Jira REST API.
First, make two tasks:
1 2 3 4 5import { task } from '@forge/workflows'; const summarise = task(async (issueKey: string) => summariseIssue(issueKey)); const postComment = task(async (issueKey: string, text: string) => addComment(issueKey, text));
Calling summarise(issueKey) gives you a future of the summary. Nothing has run yet.
Add a step with .pipe(). The step receives the summary and calls the second task:
1 2summarise(issueKey).pipe((summary) => postComment(issueKey, summary)); // a chain, not started yet
Finally, call .start() to send the chain off as a run. Put the chain in a named function and return the result of
.start():
1 2 3 4 5export const summariseAndComment = (issueKey: string) => summarise(issueKey) // a future of the summary .pipe((summary) => postComment(issueKey, summary)) // the next step .start(); // start a run; resolves to { runId }
Call this function from a resolver, trigger or event handler. It returns as soon as the run has started:
1 2const { runId } = await summariseAndComment('JRA-1');
The run carries on in the background. summarise runs in one invocation, and postComment runs in another when it
finishes. Later, check on it with runs.get:
1 2 3 4import { runs } from '@forge/workflows'; const run = await runs.get(runId); // { state: 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED', result?, ... }
To run a task for every item in a list, call .map() with the task, then .collect(). collect() gives you one
future of all the results, in the same order as the items. The rest of the chain works the same way:
1 2 3 4 5 6 7export const summariseIssues = (issueKeys: string[], reportIssueKey: string) => issueKeys .map(summarise) // one task call per issue, run in parallel .collect() // a future of every summary, in order .pipe((summaries) => postComment(reportIssueKey, summaries.join('\n\n'))) .start();
By default, at most 10 calls run at once. To change this, pass concurrency to
collect().
A future looks like a Promise, but you can't await it. Its value is only available to the next step in the
chain. To use a run's result outside the chain, read it with runs.get, or have the last step write it somewhere,
such as a Jira comment or app storage.
Keep these in mind when you write tasks:
manual@2026 bundler isn't supported.manifest.yml must include the storage:app scope, because workflows keep the state of each run in your
app's storage. forge deploy and forge tunnel fail if the scope is missing.
Rate this page: