Last updated Feb 23, 2021

Part 1: Build a Jira hello world app

This tutorial will walk you through creating a sample Forge app for Jira. There are three parts to the tutorial:

  1. This page: describes creating, changing, and installing a simple hello world app. The focus is on learning the CLI commands needed to work with apps.
  2. Call a Jira API: describes how to make API calls to the Jira REST API.
  3. Change the frontend with the UI kit: describes how to use UI kit components.

We recommend you work through all three parts to get a good understanding of how to develop apps with Forge.

Before you begin

Complete Getting started before working through this tutorial.

Forge apps can't be viewed by anonymous users. When testing a Forge app, you should be logged in to your Atlassian cloud developer site.

Set up a cloud developer site

An Atlassian cloud developer site lets you install and test your app on Confluence and Jira products set up for you. If you don't have one yet, set it up now:

  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.

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:

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

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.

Create your app

Create an app based on the Jira issue panel template.

When you create a new app, Forge will prompt you to set a default environment. In this tutorial we use the development environment as our default. Learn more about staging and production environments.

  1. Navigate to the directory where you want to create the app. A new subdirectory with the app’s name will be created there.

  2. Create your app by running:

    1
    2
    forge create
    
  3. Enter a name for your app (up to 50 characters). For example, hello-world-app.

  4. Select the UI kit 2 (Preview) category.

  5. Select the Jira product.

  6. Select the jira-issue-panel template.

  7. Change to the app subdirectory to see the app files:

    1
    2
    cd hello-world-app
    

jira-issue-panel template

The app we'll create will display an issue panel on all Jira issues, and will have a function that provides the contents of the panel.

The jira-issue-panel template uses Node.js and has the following structure:

1
2
hello-world-app
├── README.md
├── manifest.yml
├── package-lock.json
├── package.json
└── src
    ├── frontend
    │   └── index.jsx
    ├── index.js
    └── resolvers
        └── index.js

Let’s have a look at what these files are:

You can manage, distribute, and monitor your apps in the developer console.

Change the panel title

This app displays content in a Jira issue panel using the jira:issuePanel module. Jira shows the title of the jira:issuePanel as the panel's heading. Let's change the title to include your name.

  1. In the app’s top-level directory, open the manifest.yml file.
  2. Find the title entry under the jira:issuePanel module.
  3. Change the value of title from hello-world-app to Forge app for <your name>. For example, Forge app for Mia.

Your manifest.yml file should look like the following, with your values for the title and app ID:

1
2
modules:
  jira:issuePanel:
    - key: hello-world-hello-world-issue-panel
      resource: main
      resolver:
        function: resolver
      render: native
      title: jira-hello-world
      icon: https://developer.atlassian.com/platform/forge/images/icons/issue-panel-icon.svg
  function:
    - key: resolver
      handler: index.handler
resources:
  - key: main
    path: src/frontend/index.jsx
app:
  id: '<your app id>'

Install your app

To use your app, it must be installed onto an Atlassian site. The forge deploy command builds, compiles, and deploys your code; it'll also report any compilation errors. The forge install command then installs the deployed app onto an Atlassian site with the required API access.

You must run the forge deploy command before forge install because an installation links your deployed app to an Atlassian site.

  1. Navigate to the app's top-level directory and deploy your app by running:

    1
    2
    forge deploy
    
  2. Install your app by running:

    1
    2
    forge install
    
  3. Select your Atlassian product using the arrow keys and press the enter key.

  4. Enter the URL for your development site. For example, example.atlassian.net. View a list of your active sites at Atlassian administration.

Once the successful installation message appears, your app is installed and ready to use on the specified site. You can always delete your app from the site by running the forge uninstall command.

Running the forge install command only installs your app onto the selected product. To install onto multiple products, repeat these steps again, selecting another product each time. Note that the Atlassian Marketplace does not support cross-product apps yet.

You must run forge deploy before running forge install in any of the Forge environments.

View your app

With your app installed, it’s time to see the app on an issue.

  1. Create a new Jira issue. Learn more about Jira issues.
  2. In the issue panel of that issue, select the button displaying the Atlassian logo. Your app should display like the example below.

A Jira issue displaying the hello world forge app

  1. To view new changes in your app, run forge deploy again, or run forge tunnel. This is explained fully in the next section.

While your app is deployed to either a development or staging environment, (development) or (staging) will appear in your app title. This suffix is removed once you've deployed your app to production.

Deploy app changes

Once your app is installed, it will automatically pick up all minor app deployments so you don't need to run the forge install command again. Minor deployments are changes that don't modify app permissions in the manifest.yml file. You can deploy the changes onto your developer site or Bitbucket workspace by using one of two methods:

  • Manually, by running the forge deploy command.
  • Automatically, by running the forge tunnel command.

Once your app is installed, changes in the manifest are picked up automatically after running forge deploy. However, due to the eventually-consistent nature of our system, you may need to wait up to 5 minutes for changes in the manifest to be reflected in the product.

Tunneling runs your app code locally on your machine via the Forge CLI and ngrok. It allows you to speed up development by avoiding the need to redeploy each code change, and by seeing each invocation as it executes. The Forge tunnel works similarly to hot reloading, so any changes you make to your app code can be viewed on your Atlassian site or Bitbucket workspace without losing the current app state. You don’t need to run any other commands; you only need to refresh the page.

To use the forge tunnel command, Docker must be set up and running. To learn about Docker, visit the Docker getting started guides.

If you don't want to run Docker, you can redeploy your app after each code change with the forge deploy command. You will also need to modify the manifest.yml file to specify a runtime for the app field:

1
2
  app:
  id: <your app id>
  runtime:
    name: nodejs18.x
  1. Once Docker is set up, you can start tunneling by running:
1
2
forge tunnel

You should see output similar to:

1
2
Running your app locally with Docker. The tunnel displays your usage from everywhere
the app in the development environment is installed.
Press Ctrl+C to cancel.

Checking Docker image... 100%
Your Docker image is up to date.

Listening for requests on local port 37363...

Reloading code...
App code reloaded.

You can now automatically deploy changes to your codebase and install packages, while tunneling. These changes appear on the Atlassian site or Bitbucket workspace where your app is installed.

  1. When you are ready to close the tunnel, press Control + C.

The forge tunnel command only forwards traffic when the user (in Jira, Confluence, Jira Service Management or Bitbucket) matches the Forge CLI user. For security reasons, you can’t see the traffic of other users.

For important caveats on how forge tunnel works, see Tunneling.

Next step

In the next tutorial, you'll learn how to make API calls to Jira using Forge. This tutorial uses the forge tunnel, so make sure you are familiar with using this command.

A button to go to the next tutorial

Rate this page: