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.

Video 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.

Before you begin

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:

    1

    node --version

    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 sudo, update the Node.js configuration to allow global module installs using binaries by running:

    1

    npm config set unsafe-perm true

• Docker (version 17.03 or later).

  • To check your Docker version, run the following in the terminal:

    1

    docker --version

  • Note: Forge documentation doesn't include sudo 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

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

   You should see a version number reported in the terminal:

   1

   0.13.0

   If a version number is not shown then the installation failed. Repeat step 1 and look for errors reported in the terminal.

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

Set up an Atlassian cloud developer site

Create a developer site where you can install and test your app. The developer site has Confluence and all of the Jira applications installed.

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.

• Build a Jira hello world app
• Build a Confluence hello world app