Part 1: Build a Jira hello world app

This tutorial walks through creating a Forge app to display content on a Jira issue.

Before you begin

Complete Getting started before working through this page.

Create your app

Create an app based on the Jira issue panel template.

Note, Forge provides multiple environments where you deploy the app. This tutorial uses the CLI default, the development environment. See Environments to learn more.

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

2. Create your app by running:

   1

   forge create

   1. Enter a name for your app (up to 50 characters). For example, hello-world-app.
   2. Select the jira-issue-panel template.

3. Change to the app subdirectory to see the app files.

   1

   cd hello-world-app

1
Error: Account does not have app creation enabled...

jira-issue-panel template

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

1
2
3
4
5
6
7

hello-world-app
|-- src
|   `-- index.jsx
|-- manifest.yml
|-- package.json
|-- package-lock.json
`-- README.md

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

• index.jsx: Where you write the behavior of the app.
• manifest.yml: Describes your app. It contains the name and ID of your app, along with the modules it uses. This app displays an issue panel on all Jira issues and has a function that provides the contents of the panel.
• package.json: The app’s Node.js metadata. See the Node documentationfor more information.
• package-lock.json: Records the version of the app’s dependencies.
• README.md: Information about the app. We recommend updating this as you change the behavior of the app.

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
3
4
5
6
7
8
9
10
11
12

modules:
  'jira:issuePanel':
    - key: hello-world-app-hello-world-panel
      function: main
      title: Forge app for Mia
      icon: https://developer.atlassian.com/platform/forge/images/issue-panel-icon.svg
  function:
    - key: main
      handler: index.run
app:
  id: '<your app id>'
  name: hello-world-app

Deploy and install your app

Any time you make changes to the code, deploy your app using the forge deploy command. This command builds, compiles, and deploys your code, and reports any compilation errors.

To install your app on a new site, run the forge install command. Once the app is installed on a site, it will automatically pick up all minor app deployments, which means you don't need to run the install command again. A minor deployment includes any change that doesn't modify app permissions in the manifest.

In the Forge development environment, your app is deployed with all available OAuth scopes. Later in this tutorial, you’ll learn how to restrict your app to request just the access it needs.

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

   1

   forge deploy

2. Install your app by running:

   1

   forge install

   1. Select your Atlassian product using the arrow keys and press the enter key.

      Note: 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.

   2. Enter the URL for your development site. For example, example.atlassian.net.

Once the successful installation message appears, your app is installed and ready to use on the specified site.

Note, you need to 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.
2. View the issue you created.

The app is shown in an issue panel after clicking the Forge app for Mia button. Once expanded, the app displays on the page, like the example below.

Note, 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.

Next step

See Part 2: Call a Jira API to learn how to make API calls to Jira with Forge.