Promote an app to staging or production

This page describes how to take your existing Forge app from the development environment and share it with your users in a production environment. You'll learn about Forge environment restrictions and how to request the minimum set of permissions from your users.

Environments

When you call forge create, we automatically create three environments for you:

• development
• staging
• production

Environments are where you deploy your app. Once an app is running in an environment, you can install it from that environment on to an Atlassian site with forge install.

We recommend using the development environment for testing your changes, staging for a stable version of your app, and production as the version of your app that’s ready for use.

By default, the CLI will run commands for the development environment unless you specify another with the --environment flag.

While your app is deployed to development, your app title will have the suffix (DEVELOPMENT). Similarly, while your app is deployed to staging, it will have the suffix (STAGING). Once you deploy your app to production, your app title will no longer have any suffix.

Environment restrictions

When using the staging environment, you can't use the forge tunnel command. You'll need to redeploy your app using forge deploy each time you make a code change.

When using the production environment, you can't use the forge tunnel or forge logs commands. To debug issues, you’ll need to redeploy your affected code to the staging or development environments where you have access to debugging tools. For apps installed on sites you don’t have access to, you’ll need to ask the app user to download the production logs for your app and send them to you.

Configure API scopes

Forge apps must explicitly declare which scopes they require in the manifest.yml file to use the authenticated Product Fetch APIs.

See the Permissions page for a summarized table of Forge supported OAuth 2.0 scopes for all Atlassian cloud products. You can also find supported scopes in each product's REST API documentation on a per operation basis.

See the Add scopes to call an Atlassian REST API page for step-by-step instructions on adding new scopes.

Deploy to a specific environment

To deploy to a specific environment, provide the -e argument to the Forge CLI commands.

1. Navigate to the app's top-level directory and deploy your app by running:

   1

   forge deploy -e production

2. Install your app by running:

   1

   forge install -e production

   1. Select the product.
   2. Enter the URL for your development site (for example, example.atlassian.net).
   3. Review the scopes your app is requesting then answer y.

Note, to enable users to use your app, you will need to go to the developer console and enable sharing. For more information, see Distribute your apps.