Introduction to Runs on Atlassian

The Runs on Atlassian program helps customers easily identify Forge apps that have no data egress and have data residency-enabled storage. The program applies the Runs on Atlassian badge on eligible apps, which helps communicate capabilities that can benefit enterprise customers that may have strict data privacy requirements.

In general, Runs on Atlassian addresses the following requirements from customers:

1. No data egress by default and give customers controls to manage the risk of egress through logs
2. Support data residency that matches data residency provided by the host product
3. Provide a programmatic way for Atlassian to verify the above requirements

Eligibilty requirements

Eligibility for the Runs on Atlassian badge will be automatically detected and applied on apps that meet the qualifications. Partners do not need to apply or opt in to receive the badge.

To determine whether your Forge apps meet the requirements for Runs on Atlassian, start by checking your manifest file for egress permissions. You can also use the Forge CLI to check the eligibility of an app.

Eligible apps do not list any of the following in the manifest:

• External resource domains (Custom UI external permissions, fetch.backend, fetch.frontend, etc.)
• Remotes
• Connect modules
• Providers
• Dynamic web triggers

Eligible apps can use web triggers, only if the apps use static web triggers.

Eligible apps must also do either of the following:

• use data residency-enabled Forge storage,
• or store data in-product using product entity properties.

As new Forge storage capabilities are introduced, in EAP or Preview stages, these features may not support data residency until they reach general availability.

Sample manifest structure

The following are examples of how the manifest file may look, depending on the eligibility of an app for Runs on Atlassian.

Runs on Atlassian

Example

1
2
permissions:
  scopes:
    - read:content-details:confluence
    - read:content.property:confluence
    - write:content.property:confluence

Not Runs on Atlassian

Example

1
2
permissions:
  external:
    fetch:
      backend:
        - '*.example-dev.com'
  fonts:
    - 'https://www.example-dev.com/fonts.css'
  scripts:
    - 'https://www.example-dev.com/script.js'

Example

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

Eligibility check of apps

You can check the eligibility for Runs on Atlassian for any app at any time. During app deployment, the Forge CLI automatically for checks eligibility as well. You can also check the eligibility for a previous major version of an app.

To know more about checking app eligibility for Runs on Atlassian, go to the Forge CLI documentation.

Eligibility check at any time

Navigate to the app's top-level directory and check its eligibility by running:

1
2
forge eligibility

If your app is eligible, you should see output similar to:

1
2
The version of your app [2.14.0] that's deployed to [development] is eligible
for the Runs on Atlassian program.

If your app is not eligible, you should see output similar to:

1
2
The version of your app [2.16.0] that's deployed to [development] is not eligible
for the Runs on Atlassian program.
- App is using remote services
- App has Connect modules

You will see all applicable reasons for ineligibility, which helps narrow down the necessary changes to the app.

Eligibility check at app deployment

When deploying your app to any environment, the Forge CLI automatically detects any changes that may impact the app's eligibility for Runs on Atlassian.

If your app is eligible, you should see output similar to:

1
2
The version of your app [2.14.0] that was just deployed to [development] is eligible
for the Runs on Atlassian program.

If your app is not eligible, you should see output similar to:

1
2
The version of your app [2.16.0] that was just deployed to [development]
is not eligible for the Runs on Atlassian program. Run forge eligibility to know more.
To know more about Runs on Atlassian, go to: https://go.atlassian.com/runs-on-atlassian

By running forge eligibility, you should see output similar to:

1
2
App [2.16.0] in [development] is not eligible for Runs on Atlassian.
- App is using remote services
- App has Connect modules

You will see all applicable reasons for ineligibility, which helps narrow down the necessary changes to the app.

Eligibility check for previous major versions

You can check the eligibility for a previous major version of an app at any time. This helps narrow down at which major version the app has either lost or gained its eligibility for Runs on Atlassian.

Navigate to the app's top-level directory and check the eligibility of a major version by running:

1
2
forge eligibility --major-version [version]

If the app was eligible for Runs on Atlassian at the specified major version, you should see output similar to:

1
2
The version of your app [1.18.0] that's deployed to [development] is eligible
for the Runs on Atlassian program.

Removal of egress

Consider doing the following as necessary:

1. Remove egress URLs for UI

We've introduced several changes for the loading of images and media in Custom UI apps so that:

1. Custom UI apps now allow-list the host product
2. Atlassian-hosted avatars now load by default

Effectively, this means the following domains are now allowed by default:

• images

  • hostname (For example, my-tenant.atlassian.net. Custom domains are also allowed.)
  • *.wp.com
  • secure.gravatar.com
  • images.unsplash.com
  • api.media.atlassian.com
  • api.atlassian.com
  • pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net (for emojis)
  • avatar-management--avatars.us-west-2.prod.public.atl-paas.net

• media

  • hostname (For example, my-tenant.atlassian.net. Custom domains are also allowed.)

• fetch.client

  • api.atlassian.com/gateway/api/emoji/ (to fetch list of emojis)

• frames

  • hostname (For example, my-tenant.atlassian.net. Custom domains are also allowed.)

2. Remove api.media.atlassian.com for Atlassian product API redirects

Atlassian product API redirects are now treated as internal traffic by the Forge Node.js runtime. You can now remove these backend egress declarations from your app’s manifest. Note, you may still need to include such declarations in other egress sections for Custom UI apps, like for media, images, and others.

3. Migrate from dynamic to static web trigger modules

Web triggers are eligible for Runs on Atlassian if they are defined as static. The following web triggers are not eligible for Runs on Atlassian:

• Existing web triggers without a type defined
• Web triggers explicitly defined as dynamic

However, these web triggers can be migrated to static web triggers. Consider your use case for your web trrigger module and whether it can be defined as static. Find out more about web trigger types in the web trigger manifest reference.

Public roadmap and changelog

We’ve recently updated the Forge public roadmap, making it easier to track in progress and upcoming improvements to Forge. If you haven’t already, we recommend bookmarking the roadmap and changelog so you can stay across new Forge features that let you build your app more natively.

Timeline: Partner and customer launches

Known issues

Issues when loading avatars, attachment thumbnails, and other media in Custom UI apps

When avatars, attachment thumbnails, and other media are fetched from Jira APIs and passed to <img> tags in Custom UI apps, the images may not load in some cases. This is because Jira expects the requests to the APIs to be authenticated, which is not happening when URLs are passed to <img> tags.

Some workarounds to ensure images load correctly:

Option 1

Make the requests to the APIs from backend to fetch content as blob. Then, convert it to base64 and pass it to the img-src. Since the requests are made from backend, these will be authenticated as expected, and the images will load correctly.

Option 2

Replace the base path of the URLs with the base path of your host. If the URL returned from Jira APIs is in the format: https://api.atlassian.com/ex/jira/tenant-id/rest/api/3/attachment/thumbnail/content-id, replace it with: https://my-tenant.atlassian.net/rest/api/3/attachment/thumbnail/content-id.

Issues when fetching list of emojis

To render emojis in your app, internal APIs are used to access the list of emojis available. We’ve allow-listed the following:

• api.atlassian.com/gateway/api/emoji/ for fetch.client to list emojis
• pf-emoji-service--cdn.us-east-1.prod.public.atl-paas.net to fetch emojis

However, if the API for getting the list of emojis is accessed using tenant-host (for example, https://my-tenant.atlassian.net/gateway/api/emoji/, this may be blocked by the C0RS policy. As a workaround, we recommend using the allow-listed domain api.atlassian.com/gateway/api/emoji/ to fetch the list of emojis.

Issues when running the app using Forge tunnel

When running the app using Forge tunnel, some of the default allow-listed domains might not work. This means that some CSP policies are breaking during the tunnel experience, as the hostname is not matching the allowed value. Though we don’t have a fix for this at the moment, the team is aware of this particular limitation.

We also release updates to the Forge tunnel along with the Forge CLI release. This means there may be delays in any behavior updates between deployed Custom UI apps (which gets platform code changes instantly) and the tunnel experience (which requires a new version of the CLI to be released).