Rate this page:
This tutorial will walk you through creating a sample Forge app for Jira. There are three parts to the tutorial:
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.
Call a Jira API: describes how to make API calls to the Jira REST API.
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.
Complete Getting started before working through this page.
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.
Create an app based on the Jira issue panel template.
Forge provides multiple environments where you deploy the app. This tutorial
uses the CLI default, the
development environment. Learn more about staging and production environments.
Navigate to the directory where you want to create the app. A new subdirectory with the app’s name will be created there.
Create your app by running:
Enter a name for your app (up to 50 characters). For example, hello-world-app.
Select the UI kit category.
Select the jira-issue-panel template.
Change to the app subdirectory to see the app files:
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.
jira-issue-panel template uses Node.js and has the following structure:
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. This file contains the name and ID of the app, the app permissions, and the modules the app uses.
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.
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.
titleentry under the
Forge app for <your name>. For example, Forge app for Mia.
manifest.yml file should look like the following, with your values for the
title and app ID:
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>'
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.
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.
Navigate to the app's top-level directory and deploy your app by running:
Install your app by running:
Select your Atlassian product using the arrow keys and press the enter key.
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.
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.
With your app installed, it’s time to see the app on an issue.
forge deployagain, or run
forge tunnel. This is explained fully in the next section.
While your app is deployed to either a development or staging environment,
(STAGING) will appear in your app title. This suffix is removed once you've
deployed your app to production.
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 by using one of two methods:
Once your app is installed, changes in the manifest are picked up automatically after running
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 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 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.
Once Docker is set up, you can start tunneling by running:
You should see output similar to:
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 where your app is installed.
When you are ready to close the tunnel, press Control + C.
forge tunnel command only forwards traffic when the user in Jira, Confluence, or Jira
Service Management 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
In the next tutorial, you'll learn how to make API calls to Jira using Forge. This tutorial
forge tunnel, so make sure you are familiar with using this command.
Rate this page: