Overview

The manifest contains three required top-level properties: app, modules, and permissions, and number of optional properties. For example:

1
2
app:
  id: "ari:cloud:ecosystem::app/406d303d-0393-4ec4-ad7c-1435be94583a"
  licensing:
    enabled: true

Property	Required	Description
`app`	Yes	Identifying information, licensing details, and app storage (EAP). See App to learn more.
`modules`	Yes	A list of the modules used by the app. See Modules to learn more.
`permissions`	Yes	A list of the permissions required by the app. See Permissions to learn more.
`connectModules`		A list of the Connect modules used by the app.
`endpoint`		A list of remote endpoints referenced by remote resolver invocations. See Endpoint to learn more.
`providers`		Authentication providers used by the app. See Providers to learn more.
`remotes`		A list of remote services required by the app (along with additional options for declaring egress details for data residency). See Remotes to learn more.
`resources`		A list of the resources used by the app. See Resources to learn more.
`environment`		A list of environment variables to be parsed by the Forge CLI for entire or partial field values. After specifying a variable in `environment`, you can declare it in any field by enclosing it in `${` and `}`. See Environment to learn more.
`translations`		A list of translation resources supported by the app, including the fallback configurations for when a desired translation is not available. The `translations` property is available to participants of the Internationalization for Forge EAP. See Translations to learn more.

App

The app dictionary contains properties about your Forge app. Some of these are populated as part of the forge create command (for example, id).

Property	Required	Description
`id`	Yes	A unique Atlassian resource identifier (`ari`) assigned to your app.
`connect`		Details specific to Adopting Forge from Connect. This is required if the manifest has `connectModules`. See Connect to learn more.
`licensing`	No	The app's licensing state. To enable licensing for your app, add the `enabled` field attribute and set its value to `true`. See licensing to learn more.
`package`	No	Settings relating to packaging the Forge application. See Packaging to learn more.
`runtime`	Yes	Settings relating to the Forge runtime. See Runtime to learn more.
`storage`	No	A list of custom entities and their respective indexes. Custom entities are user-defined data structures for storing app data. Forge's storage API lets you query data stored in these structures using a wide array of query conditions. These query conditions make it possible to build advanced, complex queries to suit your app's operations. See Custom entities to learn more.

Runtime

The runtime property lets you configure the Forge runtime using the following settings:

Setting	Required	Type	Description
`snapshots`	No	`boolean`	Whether a snapshot of the app is taken at deployment time. Default value is `true`. This setting is only used in the legacy runtime.
`name`	Yes	`string`	Lets you specify the Forge runtime environment version on which to deploy your app. This field supports the following values: `nodejs18.x`: (deprecated) specifies the Node.js 18 runtime version. This version runs on a standard Node.js 18 environment. See Runtime for more information about the this runtime version. `nodejs20.x`: specifies the Node.js 20 runtime version. This version runs on a standard Node.js 20 environment. See Runtime for more information about the this runtime version. `nodejs22.x`: (recommended) specifies the Node.js 22 runtime version. This version runs on a standard Node.js 22 environment. See Runtime for more information about the this runtime version. `sandbox`: (deprecated) specifies the legacy version of the Forge runtime. See Legacy runtime (deprecated) for more information about this runtime version.

The legacy Javascript sandbox runtime is now deprecated. This means that Forge can only create new apps on the latest runtime version. In addition:

From October 29, 2024: Forge apps that haven't been updated since January 1, 2023 will no longer function.
From February 28, 2025: All Forge apps still running on the legacy runtime version will no longer function.

If your app is running on the Javascript sandbox runtime, we strongly advise that you upgrade to the latest runtime.

Packaging (preview)

This section describes a Forge preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.

We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA). For more information, see Forge release phases: EAP, Preview, and GA.

The package property lets you configure how the application's source code is packaged during deployment.

Setting Type Description

Setting	Type	Description
`extraFiles`	`string[]`	Extra files to copy to the deployed application. These can include application data, configuration files or additional programs the application might want to read or launch. Each item in this list can point to a single file or a glob pattern. When the Forge function runs, the files matching the specified patterns are available in the application directory.

extraFiles

string[]

Extra files to copy to the deployed application. These can include application data, configuration files or additional programs the application might want to read or launch.

Each item in this list can point to a single file or a glob pattern.

When the Forge function runs, the files matching the specified patterns are available in the application directory.

Reading packaged files

You can read packaged files using the fs module.

1
2
import { readFileSync } from 'node:fs';

const data = readFileSync('./file.txt', 'utf8');

Executing packaged binaries

If you intend to add extra executables to your application and call them from functions, make sure they are compatible with the Forge runtime environment. You might want to use statically linked executables if possible, or include the required libraries together with the executable.

You can execute packaged binaries using the child_process module.

1
2
import { execFileSync } from 'node:child_process';

const stdout = execFileSync('./binary', ['--args'], {
  stdio: 'pipe',
  encoding: 'utf8',
});

While you can read files and execute binaries packaged with your app, you must not persist customer data to disk or allow long-running child processes to retain it. If you aren't sure whether a process will cache the data, don't allow it to persist beyond a single function invocation.

Refer to Expanded developer responsibilities for more information.

Connect

Connect apps that have adopted Forge modules can include Connect modules and a Connect key.

Property Required Description

Property	Required	Description
`key`	Yes	A key to identify the Connect app and its components. `key` is environment specific. See how to manage environments when using Forge from your Connect app. Note: The production environment of the app must match the Atlassian Marketplace key.
`remote`		The key of the `remotes` entry that holds the Connect app baseUrl. This is required if the manifest has `connectModules`.

key

Yes

A key to identify the Connect app and its components.

key is environment specific. See how to manage environments when using Forge from your Connect app.

Note: The production environment of the app must match the Atlassian Marketplace key.

remote

The key of the remotes entry that holds the Connect app baseUrl.

This is required if the manifest has connectModules.

Example

1
2
remotes:
  - key: connect-app-server
    baseUrl: https://hello-world-app.example.com
app:
  connect:
    key: hello-world
    remote: connect-app-server