Before any great developer sets off on their quest, they must first gear up. Think of this as forging your sword, gathering supplies, and unlocking the map—your first milestone in the adventure ahead.
FYI, to build apps with Forge, you’ll be using JavaScript. It’s also helpful to be familiar with React.
To complete this stage, you'll need to gather the essential tools in your inventory:
🔧 Install Node.js
Forge requires a Long-Term Support (LTS) version. Choose the one fit for your operating system and follow the setup guide.
🧙‍♂️ Install the Forge CLI
The Command Line Interface (CLI) is your magic wand—your primary way to cast commands and deploy apps. You’ll use it to create, build, and manage everything on your journey.
🗝️ Authenticate with an Atlassian API Token
Think of this as your access rune—connecting your Forge powers with your Atlassian identity.
🏰 Set Up Your Atlassian Developer Test Site
This is your personal sandbox realm where you can safely build, test, and tinker without fear of breaking anything in production.
After installing the Forge CLI, checkout the Forge CLI docs to get acquainted with each command.
The Forge CLI won’t run without a properly installed LTS version of Node.js. Be sure to follow the Node.js setup instructions for your system before continuing.
The Forge CLI requires a fully supported LTS release of Node.js installed; namely, versions 18.x, 20.x or 22.x.
Forge developers on macOS should use Node Version Manager (nvm) to configure the environment.
Install nvm.
Select the latest Node.js LTS release by running the following in the terminal:
1 2nvm install --lts nvm use --lts
If nvm command doesn't work, try restarting the terminal.
Check your Node.js version, run the following in the terminal:
1 2node --version
Which outputs your node version.
Skip this step if you have successfully completed Set up Node.js section.
You can install Node.js using the macOS installer, however this results in permission errors when working with the Forge CLI. If you must use the installer, you'll need to enable unsafe permissions to use the Forge global package when installing Node.js using this method.
Download the LTS installer from Node.js.
Install the package.
Configure npm, permitting unsafe permissions:
1 2npm config set unsafe-perm true
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:
1 2npm install -g @forge/cli
Verify that the CLI is installed correctly by running:
1 2forge --version
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 forge --help.
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 sudo or root user when running forge. 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:
1 2forge login
You'll be asked whether to allow Forge to collect usage analytics data:
1 2Allow Forge to collect CLI usage and error reporting information?
Answering Yes 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.
For information about how Atlassian collects and handles your data, read our Privacy Policy.
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:
1 2âś” Logged in as Adventurer Charlie
The Forge CLI uses your operating system's keychain to securely store your login details.
Any command after forge login 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 libsecret installed to perform this step.
To install and test your app, you'll need to create a test site for it. For Confluence and Jira apps, you need an Atlassian cloud developer site; for Bitbucket apps, you'll need a shared Bitbucket team space.
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.
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 limits on the numbers of users you can create are as follows:
Now that you've set up your development environment, and a test site, it's time to review essential Forge knowledge.
Rate this page: