Rate this page:
Welcome to developing with the Forge platform for Atlassian’s cloud products. Work through the steps below to set up your development environment. To get started using Forge, you’ll install the CLI, log in with an Atlassian API token, and create an Atlassian developer site that has Confluence and all of the Jira applications installed.
After setting up, you'll go through a three-part tutorial to create a simple hello world app for Confluence, Jira, or Jira Service Management!
The Forge CLI requires a fully supported LTS release of Node.js installed; namely, versions 14.x, 16.x, or 18.x.
You'll also need to install Docker.
For setup instructions, select your platform from the list below:
After installing the Forge CLI, follow the prompts in the terminal to build a hello world app. For a complete explanation of each step, continue reading along with the documentation.
Install the Forge CLI using npm. You’ll install the CLI globally so that the commands can be run across your system.
Install the Forge CLI globally by running:
npm install -g @forge/cli
Verify that the CLI is installed correctly by running:
You should see a version number reported in the terminal:
If a version number is not shown then the installation failed. Repeat step 1 and look for errors reported in the terminal.
With the CLI installed, view the complete list of Forge commands by running .
Create or use an existing Atlassian API token to log in to the CLI. The CLI uses your token when running commands.
Log in to the Forge CLI to start using Forge commands.
Do not use or root user when running . Doing so may cause issues with file permissions and ownership, potentially leading Forge CLI not functioning properly when run by a non-privileged user.
Start the process by running:
You'll be asked whether to allow Forge to collect usage analytics data:
Allow Forge to collect CLI usage and error reporting information?
Answering will allow Forge to collect data about your app's deployments and installations (including error data). This, in turn, helps us monitor Forge's overall performance and reliability. The collected data also helps us make better decisions on improving Forge's feature set and performance.
Enter the email address associated with your Atlassian account.
Enter your Atlassian API token. You copied this to the clipboard in step 5.
You will see a message similar to this confirming you are logged in:
✔ Logged in as Mia Krystof
The Forge CLI uses your operating system's keychain to securely store your login details. Any command after that requires authentication will read your credentials from the keychain. When this occurs, your keychain may prompt you for access; approve it to allow the CLI to run the command.
On Linux, you'll need installed to perform this step.
If a keychain isn't available, you can store your login email and token through the environment variables and , respectively. In continuous integration environments, you can store these environment variables as secrets for your builds. For more information, read our tutorial on setting up continuous delivery for Forge apps.
Otherwise, you can also set environment variables manually:
read FORGE_EMAIL # Enter email read -s FORGE_API_TOKEN # Enter API token (will not be displayed) export FORGE_EMAIL FORGE_API_TOKEN
This applies to all commands that require to be run first.
Creating an Atlassian cloud developer site allows you to install and test your app with Confluence and Jira products set up for you. You can install your app to multiple Atlassian sites however, app data won't be shared between separate Atlassian sites, products, or Forge environments.
The Atlassian Marketplace doesn't currently support cross-product apps. If your app supports multiple products, you can publish two separate listings on the Marketplace, but your app won't be able to make API calls across different products and instances/installations.
The limits on the numbers of users you can create are as follows:
You're all set up to build a Forge app in Confluence, Jira, or Jira Service Management.
Rate this page: