Runtime

The Forge app runtime includes a set of APIs that provide additional functionality to the Forge platform. You can use these APIs to interact with REST endpoints and to store data.

This runtime runs in a standard Node.js 18 environment; we also intend to support newer versions as they become . As such, you can import any built-in, local, or third-party Node modules into your app. This provides compatibility with all Node libraries and NPM packages, allowing you to leverage the entire JavaScript developer ecosystem.

Legacy runtime

Apps created and last deployed before Apr 17, 2024 may still be running on a legacy version of the Forge runtime. We strongly recommend that you migrate your app to the latest version of the Forge runtime.

For details about the previous runtime (including instructions for migration), see Migrating from the legacy runtime

Before you begin

To access Forge APIs from your app, first install the latest API package by running:

1
2
npm install @forge/api

This package will enable the use of the following APIs:

• Fetch API
• Product Fetch API
• Storage API
• Properties API

Invocation

The Forge runtime allows your app to run directly on a secure VM environment. Your app will be provided with 512MB of memory per invocation. For a complete list of resource limits provided per app invocation, refer to Platform quotas and limits.

Context

At invocation time, Forge calls a context function. Each module receives different request parameters based on the module type.

You can also explicitly request a Forge function’s context details (for example, the environments and versions an app is executing in). See getAppContext for more information.

Developer responsibilities

Within the Forge runtime, it is your responsibility to ensure customer data does not persist across app invocations. These responsibilities are laid out in our shared responsibility model.

To comply with these responsibilities, review your app code to ensure that:

• Your app must not persist customer data or sensitive content in global state, in memory or on disk, between subsequent invocations.

• Your app must not copy customer data or sensitive content from one installation to another, unless it has been explicitly permitted by the customer.

Delayed code execution

The latest Forge runtime might keep executing the code after the function returns. For example:

1
2
resolver.define("example", () => {
  setTimeout(() => {
    fetch("...");
  }, 5000);
});

In this example, timers and other asynchronous code may continue executing even after the Forge function returns a response.

Default Content-Type header

When making API calls through requestJira, requestConfluence and requestBitbucket, outbound HTTP requests will assume a Content-type: application/json if a content type isn’t specified. However, this default will not be applied to requests to external domains using the fetch function or other HTTP clients.

HTTPS only

All external connections must be done through HTTPS; plain HTTP or TCP connections are not allowed. In addition, these connections will be implemented over a custom proxy which will only allow the following https.request options (or equivalents from third-party packages):

• auth
• headers
• host
• method
• port
  • Only 80, 8080, 443, 8443, 8444, 7990, 8090, 8085 and 8060.
• path

Console and https customizations

While the current runtime uses a full Node.js environment, some https and console methods are replaced with custom implementations. These customizations ensure external connections and logs connect to the Forge platform.

IP address range changes for outgoing connections

Outgoing connections for Forge apps currently originate from a VPC configured in the Atlassian cloud environment where the Forge functions are executed. For apps deployed the Forge runtime, outgoing connections will originate from Atlassian’s cloud infrastructure (specifically, the IP addresses listed here).

Redirects to external domains

All requests to Atlassian product APIs that return redirects to external domains are considered egress. If your app uses such redirects, you’ll need to declare those domains and add permissions for them in your manifest file:

1
2
permissions:
  external:
    fetch:
      backend:
        - 'https://www.example.com'

See Runtime egress permissions for detailed instructions.