Developer
News and Updates
Get Support
Sign in
Get Support
Sign in
DOCUMENTATION
Cloud
Data Center
Resources
Sign in
Sign in
DOCUMENTATION
Cloud
Data Center
Resources
Sign in
Runtimes
Web triggers
Async events
Workflows
Realtime events
Dynamic Modules
Customer-managed egress and remotes
License API
Installation Details API
Atlassian app REST APIs
Fetch APIs
LLMs API
Last updated Nov 11, 2026

Forge Workflows API

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.

Tasks, futures and chains

Workflows uses five ideas:

  • A task is a function you want to run in the background. You make one by wrapping a function with task().
  • Calling a task doesn't run it straight away. It gives you a future: a placeholder for the result the task will produce later.
  • You build a chain by adding steps to a future with .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.
  • Each task call runs in its own invocation, so a run can take much longer than one function is allowed to.

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.

Build a chain one line at a time

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
5
import { 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
2
summarise(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
5
export 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 }

Diagram: summariseAndComment('JRA-1') returns a run ID straight away. The summarise task runs in its own invocation and passes the summary to the postComment task, which runs in another. The run's result is read with runs.get.

Call this function from a resolver, trigger or event handler. It returns as soon as the run has started:

1
2
const { 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
4
import { runs } from '@forge/workflows';

const run = await runs.get(runId); // { state: 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED', result?, ... }

Run a task for every item

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
7
export 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();

Diagram: issueKeys.map(summarise) calls the summarise task once for every issue, at most 10 at once, each in its own invocation. collect() waits for all of them and passes the summaries, in order, to the postComment task.

By default, at most 10 calls run at once. To change this, pass concurrency to collect().

Futures aren't Promises

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.

Before you start

Keep these in mind when you write tasks:

  • Steps run in the background with the app's permissions, and have no user context. See Security.
  • A step can occasionally run twice, so make side effects safe to repeat. See Running twice.
  • Values passed between steps must be plain JSON data, and each step must finish within the function timeout. See Limits.

Requirements

  • Your app must be written in TypeScript.
  • Your app must use the default bundler. The manual@2026 bundler isn't supported.
  • Your 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.

Learn more

Rate this page: