Last updated Aug 13, 2021

Rate this page:

Getting started

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.

Before you begin

To complete this tutorial, you’ll need the following installed and running:

  • Node.js
  • Docker

For setup instructions, select your platform from the list below:

Hello world CLI overview

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.

Hello world CLI overview

Install the Forge CLI

Install the Forge CLI using npm. You’ll install the CLI globally so that the commands can be run across your system.

  1. Install the Forge CLI globally by running:

    1
    npm install -g @forge/cli

  2. Verify that the CLI is installed correctly by running:

    1
    forge --version

  3. You should see a version number reported in the terminal:

    1
    1.6.0

    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.

Log in with an Atlassian API token

Create or use an existing Atlassian API token to log in to the CLI. The CLI uses your token when running commands.

  1. Go to https://id.atlassian.com/manage/api-tokens.
  2. Click Create API token.
  3. Enter a label to describe your API token. For example, forge-api-token.
  4. Click Create.
  5. Click Copy to clipboard and close the dialog.

Log in to the Forge CLI to start using Forge commands.

  1. Start the process by running:

    1
    forge login

    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 gnome-keyring installed to perform this step.

  2. Enter the email address associated with your Atlassian account.

  3. 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
✔ Logged in as Mia Krystof

Note, the CLI uses 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.

Set up an Atlassian cloud developer site

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.

  1. Go to http://go.atlassian.com/cloud-dev and create a site using the email address associated with your Atlassian account.
  2. Once your site is ready, log in and complete the setup wizard.

The limits on the numbers of users you can create are as follows:

  • Jira Software and Jira Core: 5 users
  • Jira Service Desk: 1 agent
  • Confluence: 5 users

Next steps

You're all set up to build a Forge app in Jira or Confluence.

Rate this page: