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
Last updated Nov 18, 2026

Run long-running workflows

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.

In this tutorial, you build a Jira issue panel with a Summarise subtasks button. The button starts a workflow that summarises each subtask in parallel and joins the summaries together. The panel shows a progress bar while the workflow runs, and the summary when it finishes.

A workflow is a chain of tasks that runs in the background, one invocation per task call. Starting it gives you a run ID, which you use to check on the run. For an introduction to tasks, futures and chains, see Forge Workflows API.

Before you begin

You need a Forge app written in TypeScript, with a Jira issue panel module. To create one, see Getting started.

Step 1: Install the SDK and add the storage scope

Install the SDK:

1
2
npm install @forge/workflows

Workflows keep the state of each run in your app's storage, so add the storage:app scope to manifest.yml:

1
2
3
4
5
permissions:
  scopes:
    - read:jira-work
    - storage:app

Step 2: Write the workflow

Create src/workflows.ts:

1
2
3
4
5
6
7
8
9
10
11
12
13
import { task } from '@forge/workflows';
import { summariseIssue } from './llm';

// A task: each call runs in its own invocation.
const summarise = task(async (issueKey: string) => summariseIssue(issueKey));

export const summariseSubtasks = (issueKeys: string[]) =>
  issueKeys
    .map(summarise) // one task call per subtask
    .collect({ concurrency: 5 }) // run at most 5 at once, and wait for all of them
    .pipe((summaries) => summaries.join('\n\n') || 'This issue has no subtasks.') // the run's result
    .start(); // start a run; resolves to { runId }

Diagram: summariseSubtasks calls the summarise task once for every subtask, at most 5 at once. collect() waits for all of them, then a step joins the summaries into the run's result, which the panel reads with runs.get.

summariseIssue is your own function, for example one that calls the Forge LLMs API.

The last step's value becomes the run's result. Here, that's the joined summaries.

Step 3: Add resolvers to start the run and check on it

In src/index.ts, add one resolver that starts the workflow and one that returns the run's status. The start resolver reads the issue from the panel's context and looks up its subtasks before starting the run, because a workflow's fan-out items must be known when it starts:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import api, { route } from '@forge/api';
import Resolver from '@forge/resolver';
import { runs } from '@forge/workflows';
import { summariseSubtasks } from './workflows';

const resolver = new Resolver();

// The subtasks of an issue, as the current user can see them.
const getSubtaskKeys = async (issueKey: string): Promise<string[]> => {
  const response = await api.asUser().requestJira(route`/rest/api/3/issue/${issueKey}?fields=subtasks`);
  if (!response.ok) throw new Error(`Couldn't read ${issueKey}: ${response.status}`);
  const issue = (await response.json()) as { fields: { subtasks?: Array<{ key: string }> } };
  return (issue.fields.subtasks ?? []).map((subtask) => subtask.key);
};

// Returns { runId } as soon as the run has started.
resolver.define('start', async ({ context }) => {
  const issueKey = context.extension.issue.key as string;
  return summariseSubtasks(await getSubtaskKeys(issueKey));
});

// Returns { state, progress, result?, error? }.
resolver.define('status', ({ payload }) => runs.get(payload.runId));

export const handler = resolver.getDefinitions();

runs.get can read any run in your app, and the workflow's steps run with your app's permissions. In a real app, check that the user is allowed to start the run and to see its result. See Security.

Step 4: Show progress in the panel

In your issue panel's frontend, start the run, then call the status resolver every 2 seconds until the run finishes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import React, { useEffect, useState } from 'react';
import ForgeReconciler, { Button, ProgressBar, Text } from '@forge/react';
import { invoke } from '@forge/bridge';

const App = () => {
  const [runId, setRunId] = useState();
  const [run, setRun] = useState();

  useEffect(() => {
    if (!runId) return;
    const timer = setInterval(async () => {
      // In production, catch invoke errors, clear the timer, and show an error.
      const status = await invoke('status', { runId });
      if (!status) return clearInterval(timer);
      setRun(status);
      if (status.state !== 'RUNNING') clearInterval(timer);
    }, 2000);
    return () => clearInterval(timer);
  }, [runId]);

  const start = async () => {
    // In production, disable the button while this awaits and show invoke errors.
    // The resolver finds the issue from the panel's context, so there's nothing to send.
    const { runId } = await invoke('start');
    setRunId(runId);
  };

  if (!runId) return <Button onClick={start}>Summarise subtasks</Button>;
  if (!run || run.state === 'RUNNING') {
    const { done = 0, total = 1 } = run?.progress ?? {};
    return <ProgressBar value={done / total} />;
  }
  return run.state === 'SUCCEEDED' ? <Text>{run.result}</Text> : <Text>Failed: {run.error?.message}</Text>;
};

ForgeReconciler.render(<App />);

progress tells you how many of the subtask summaries have finished, which fills the progress bar.

Step 5: Deploy and try it

  1. Navigate to the app's top-level directory and deploy your app by running:

    1
    2
    forge deploy
    
  2. Install your app using one of the following commands:

    To install to your latest active Forge demo development site, or provision one if needed:

    1
    2
    forge install --demo-site
    

    Demo sites include realistic seeded data and are active for 90 days by default.

    To select an existing Atlassian site:

    1
    2
    forge install
    
  3. If prompted, select your Atlassian context using the arrow keys and press the enter key.

  4. If prompted, enter the URL for your development site. For example, example.atlassian.net. View a list of your active sites at Atlassian administration.

Once the successful installation message appears, your app is installed and ready to use on the specified site. You can always delete your app from the site by running the forge uninstall command.

Open an issue, click Summarise subtasks, and watch the progress bar fill as each subtask is summarised.

Next steps

  • The run keeps going if the user closes the panel. To let them come back to the result, save the run ID, for example in app storage keyed by the issue.
  • Handle failures with .catch() or collect({ settle: true }). See Errors, limits and testing.
  • Add a human approval step with waitForSignal(), or an agent tool-call loop with loop(). See the examples and the API reference.

Rate this page: