Last updated Sep 26, 2023

Preparing for your first quest

Before you begin your first quest, you'll need to make sure you've got all the tools required for the journey.

To get ready to use Forge, you’ll

  • Install the Forge CLI (Command Line Interface),
  • Log in with an Atlassian API token,
  • Create an Atlassian Developer Test Site
  • Provide credentials for ngrok
  • Familiarise yourself with the Forge CLI

Setting up your developer environment

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

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
2
    npm install -g @forge/cli

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

    1
2
    forge --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.

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.

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.

  1. Start the process by running:

    1
2
    forge login

  2. You'll be asked whether to allow Forge to collect usage analytics data:

    1
2
    Allow 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.

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

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

Signing up for a Developer Test Instance

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.

Jira and Confluence: set up a 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:

  • Confluence: 5 users
  • Jira Service Management: 1 agent
  • Jira Software and Jira Work Management: 5 users

Providing credentials for ngrok

Tunneling runs your app code locally on your machine via the Forge CLI and ngrok.

Forge tunnel uses ngrok to tunnel invocations. As ngrok does not support anonymous users, you need to set up your credentials before using tunnel command. If you don't have an ngrok account, sign up for one.

Once you have an ngrok account:

  1. Get your ngrok authtoken.
  2. Create an ngrok config file. Here's an example YAML file: 
    1
2
    version: 2
log_level: debug
region: us
authtoken: <your-ngrok-authtoken>
  3. Provide the path to the config file to Forge using the command forge settings set ngrok-config-path <file>.

Next - Essential Knowledge

Now that you've set up your development environment, and a test site, it's time to review essential Forge knowledge.

Rate this page: