Last updated Jul 2, 2024

Using the capabilities discussed on this page may make your app not eligible for Runs on Atlassian.

Go to this page to know more about the Runs on Atlassian program. To know how to check if your app is eligible for Runs on Atlassian, go to the Forge CLI documentation.

Forge remote

Forge remote allows you to integrate a Forge app with services hosted on other platforms.

This allows you to:

Call a remote backend from a Forge frontend (Custom UI or UI Kit)
Call a remote backend from a Forge function
Send product and lifecycle events (to a remote)
Configure scheduled triggers to invoke a remote backend

From your remote, you are then able to:

Access Forge storage
Call product APIs

Using Forge remote

Remote essentials - the key things you need to connect to your remote
Specifics and guides on remote capabilities:
- Calling a remote backend from a Forge frontend (Custom UI or UI Kit)
- Calling a remote backend from a Forge function
- Sending product and lifecycle events (to a remote)
- Configuring scheduled triggers to invoke a remote backend
- Accessing Forge storage (from a remote)
- Calling product APIs (from a remote)
- Perform Bitbucket git operations (from a remote)
- Remote observability - where to see metrics, logs, and debugging tools

Use cases

Some use cases for these capabilities:

Create an integration app that sends or receives data between an Atlassian product and a third-party product.
Invoke a complex existing application, for example, your own customized large language model that provides AI services to your app that runs on a non-Atlassian platform.
Provide a webhook endpoint for an external app such as Slack to send a request to an Atlassian product upon an arbitrary event.

See the code for a working reference app

Reference Forge application (frontend code):

atlassian/forge-remote-app

The Forge portion of the app demonstrates how to define:

A remote resolver for a Confluence macro using Custom UI and targeting a Node.js or Spring Boot remote endpoint.
A remote resolver for a Confluence macro using Custom UI, performing a backend invocation of a Node.js or Spring Boot remote endpoint.
A webtrigger that performs a backend invocation of a Node.js or Spring Boot remote endpoint.
A remote receiver for the avi:confluence:created:comment and avi:confluence:created:page events targeting a Spring Boot endpoint.
A remote receiver for the avi:confluence:created:page event targeting a Node.js endpoint.

Reference backend endpoints:

The remote app code demonstrates how to:

Validate and retrieve key information from a Forge Invocation Token (FIT).
Set, get, and delete an entry from Forge Storage using GraphQL.
Invoke Atlassian product APIs with app and user permissions.
Invoke a Confluence API with app permission to place a comment on a page in response to the avi:confluence:created:page event.
Invoke a Confluence API with app permissions to fetch a page in response to the avi:confluence:created:comment event.
Provide a webhook endpoint for an external app to perform a request to Confluence as an app.

Running local reference backends

You must run your own copy of the reference backends in order to be able to send and receive responses from the reference frontend. This is because the reference backends are configured to only accept requests from a specific frontend app ID.

You will need to update the remote baseUrls in the frontend app manifest to point to your own backend services. Your own reference backends must be accessible from the internet, as requests to them will be sent from the Forge platform.