Remotes

When using Connect or external authentication, or when invoking a remote backend from a Forge app using the Forge remote, the external domains that the app communicates with are listed in the remotes section of the manifest.yml file, and are referenced by key.

Properties

Property	Type	Required	Description
`key`	`string`	Yes	A key for the remote, which other modules can refer to. Must be unique within the list of remotes and have a maximum of 23 characters. Regex: `^[a-zA-Z0-9_-]+$`
`baseUrl`	`string`	Yes	Base URL of the remote resource.
`operations`	`array`	No	Indicates the purpose of the data being egressed. For now, this property only accepts four values: `storage`: app egresses data to be stored on a remote location. `compute`: app egresses data to be processed (but not stored) on a remote compute service; setting this value is required for invokeRemote to work. `fetch`: app uses a remote endpoint for client fetch permissions `other`: data is being egressed for logging, diagnostics, or any purpose other than `storage`, `compute`, or `fetch`. If a remotes entry contains no operations property, Forge will assume that the app is egressing end-user data to be stored on a remote back end. See Data residency for more information.
`auth`	`object`	No	An object that defines the authentication tokens to be provided to the remote endpoint
`auth.appUserToken.enabled`	`boolean`	No	If `true` and the remote endpoint is invoked within a user's login session, Forge includes an `appUserToken` in the Forge Invocation Token it sends to the remote app. This token can be used by the remote app when invoking an Atlassian product API, to invoke the API with the permissions of the user in whose login session the app is running. Specifically, the API will have only as much access to the site's data as that user does. For example, if the user does not have permission to see pages in a particular space or issues in a particular project, the API won't provide them access to that space or page, either. Forge modules that run outside of a user's login session, such as an app lifecycle event or product event are not associated with a user and cannot send an `appUserToken` to the remote app. If an endpoint opts to enable remote user token access, the `read:app-user-token` scope must also be specified in the Permissions section of the manifest.
`auth.appSystemToken.enabled`	`boolean`	No	If `true`, Forge includes an `appSystemToken` in the Forge Invocation Token it sends to the remote app. This token can be used by the remote app when invoking an Atlassian product API, to invoke the API with the permissions of the generic "bot user" for the app. If an endpoint opts to enable remote system token access, the `read:app-system-token` scope must also be specified in the Permissions section of the manifest.
`storage`	`string`	Yes (if `operations` property contains the `storage` value)	Indicates whether you are egressing end-user data to store it on a remote location, through the `inScopeEUD` boolean. See Data residency for more information.

Data residency

Forge apps that don't contain a remotes declaration automatically become eligible for PINNED status. This is because Forge can safely assume that the app is not storing any in-scope End-User Data on a remote back end.

When an app contains a remotes declaration, Forge will (by default) assume the app is storing in-scope End-User Data on a remote back end. Storing in-scope End-User Data on a remote back end will make your app ineligible for PINNED status.

If your app contains a remotes declaration but does not store in-scope End-User Data on a remote back-end, your app can be eligible for PINNED status. However, you’ll need to declare this explicitly:

If your app stores data on a remote back end, declare this through the storage property. If the data you’re storing remotely isn’t in-scope End-User Data, use the inScopeEUD: false boolean to indicate this:

1
2
remotes:
  - key: remote-backend
    baseUrl: "https://backend.example.com"
    operations:
      - storage
    storage:
      inScopeEUD: false

If your app egresses data that will not be stored in a remote back end, you can declare this in operations through the compute or other properties:

1
2
remotes:
  - key: remote-backend
    baseUrl: "https://backend.example.com"
    operations:
      - compute
      - fetch
      - other

If your app uses a third-party service for runtime egress permissions and doesn’t store data on a remote back end, declare this in operations through the fetch property:

1
2
permissions:
  external:
    fetch:
      backend:
        - remote: remote-backend
remotes:
  - key: remote-backend
    baseUrl: "https://backend.example.com"
    operations:
        - fetch

In this case, your fetch.backend list will use the remote back end’s key instead of the actual URL. You can use other for instances where you egress data for real-time logging, diagnostics, and other similar cases. See Permissions for more information about configuring the fetch section.

In these cases, Forge will be satisfied that your app is not storing in-scope End-User Data on a remote back end. As a result, your app will be eligible for PINNED status in the admin's Data residency interface. This also means that when your app is installed on a product with the PINNED status, so will your app:

App pinned to same location as product

See Data residency for more information about the PINNED status (for both products and installed apps).

Major version upgrades

Manifest file updates that add new remotes entry or expand an existing remote’s scope will result in a major version upgrade of your app upon deployment. This ensures that whenever an app starts egressing data to a new back end, admins can review and re-consent first before updating. Such manifest file updates include:

Manifest file update	Description
Adding a new `remotes` section	The app uses a new remote back end, and admins need to be explicitly notified whenever this happens.
Changing the `baseURL` of an existing `remotes` entry	The app now technically egresses data to a new remote back end.

Minor upgrades

Removing a remotes entry or any update that decrease an existing remote’s scope will only result in a minor upgrade. Such manifest file updates include:

Manifest file update	Description
Changing the storage property of a remotes entry from `inScopeEUD: true` to `inScopeEUD: false`	The app previously stored in-scope End-User Data on a remote back end, but now it doesn’t. This reduces the scope of the back end.
Removing one or more (but not all) purposes from an `operations` property	The remote back end’s scope is now reduced, as it is no longer being used for a specific purpose.
Moving a URL from a `fetch.backend` declaration to the `remotes` section	The remote back end hasn’t changed in scope, it is now simply declared in a different way. See Data residency eligibility and Fetch for related information.

Minor upgrades are automatic, and will not require any action by users or admins.

Example

The following example shows two remotes (remote-backend and loggingserver) that do not egress in-scope End-User Data to be stored remotely:

1
2
permissions:
  scopes:
    - "storage:app"
  external:
    fetch:
      backend:
        - remote-backend
remotes:
  - key: remote-backend
    baseUrl: "https://backend.example.com"
    operations:
      - storage
      - fetch
    storage:
      inScopeEUD: false
  - key: loggingserver
    baseURL: "https://logging.example.com"
    operations:
      - other