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 you're set up, you'll create a simple hello world example app using Jira or Confluence in a three part tutorial.
Prefer a video tutorial? Follow along as we develop a Forge app that provides a macro displaying a world map with a configuration form allowing a country to be highlighted. Selecting a country in the macro configuration will also result in the app making a REST API call to add a label to the page where the label text is the selected country name.
To complete this tutorial, you'll need:
Node.js (version 10.0.0 or later). Installing Node.js also installs npm.
To check your Node.js version, run the following in the terminal:
Important: We recommend running Node.js as your local user. If you're running Node.js as the root user, or with root privileges via , update the Node.js configuration to allow global module installs using binaries by running:
npm config set unsafe-perm true
Docker (version 17.03 or later).
To check your Docker version, run the following in the terminal:
Note: Forge documentation doesn't include when calling Docker. Linux users should read Manage Docker as a non-root user for more information.
We recommend you read and understand the Beta limitations before starting development.
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.
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.
Start the process by running:
Note: The CLI uses OSX keychain to securely store your login details. If you see a prompt for keychain access when running a command, approve it to allow the CLI to run the command. On Linux you’ll need installed to perform this step.
Enter the email address associated with your Atlassian account.
You will see a message similar to this confirming you are logged in:
✔ Logged in as Mia Krystof
Create a developer site where you can install and test your app. The developer site has Confluence and all of the Jira applications installed.
The limits on the numbers of users you can create are as follows:
You're all set up to build a Forge app in Jira or Confluence.
Rate this page: