Developing a Jira App: Distributing Your Atlassian Forge App

Application Services
Written By Chris Low & Alex Howard
Distributing Your Atlassian Forge App

In a prior installment of this blog [1], we discussed getting your Forge app up and running in a "Hello, World!" way on a test Atlassian instance. Now, perhaps your company has an Atlassian instance that employees use daily, and you'd like to test your Forge app in the real world by installing it on that instance. Another scenario is that you’re now ready to have customers for your app, so you need to distribute it to them. Let's see how that can be done!

First, a word about Forge environments…

Every Forge app can be deployed to three environments:

  • Development: This environment is the one most suited to the development-and-test cycle for your app. In that environment, the app can run in the cloud, or it can run on a developer's machine using tunneling. See [1] for more details.

  • Staging: Use this environment for a stable, pre-production version of your app. This is best suited for verification, validation, or useability testing.

  • Production: Of course, this is the environment in which your customers will use the app.

As you might expect, each environment is firewalled from the others; they don’t share in-app data, for example. However, multiple environments of the same app, potentially with different versions of the app’s code, can be installed on the same Atlassian instance, so that you can test the app against the same set of Atlassian Cloud data, such as Jira tickets:

 

As the tags to the right of the app names imply, the second is Development and the third is Staging. Production, the first one, doesn’t have such a tag.

NOTE: All usage of the app in Production will be subject to Forge platform quotas and limits [2]. Also, if the app is a paid app, Production usage of the app will be billed to your company – even such usage by your company! We recommend that most testing of your app be performed in Development and Staging, since those environments aren't subject to such limits and charges.

Also, a word about required user permissions…

Currently, only one Atlassian Cloud user can perform deployment and installation of a given Forge app – namely, the user who created the app. This is very important when you consider that you may wish to perform development on one Atlassian Cloud site, then have other users test your app on a different site. Of course, it also makes having multiple developers on the same app more challenging. On top of that, if someone leaves a company, and if they had created any Forge apps during their time at the company, then their Atlassian Cloud user might still have to exist with just enough privileges to keep the app deployable.

Atlassian has something on their roadmap to enable multiple users to “own” the same app for development purposes [3]. In the meantime, however, workarounds are required, which we’ll discuss shortly.

And Now, Hands on Your Keyboard!

Let’s say you’ve created a Forge app, called getting-started. You’ve already developed and tested it in the Development environment, and now you wish to deploy it to your Staging environment for further testing by others. Let’s do that.

Deploying Your Forge App

In Forge terminology, deployment refers to the building and deployment of a specific version of a Forge app into a Forge environment. This is the first step necessary to distribute your app, whether it be brand-new or a version with updated code.

To deploy, make sure that your app is fully built, then run the forge deploy command [4] from your app’s root directory. If you don’t specify any command-line arguments, it will deploy to the Development environment; however, we wish to deploy to Staging instead, so the command needs to specify the -e staging argument:

Installing Your Forge App

Installation refers to the installation of a particular Forge environment-app combination onto an Atlassian site, presuming that the app has been deployed to the specified environment. Whenever a given app is updated via a deployment, all installations of that app in that deployed-to environment across all Atlassian Cloud sites will be notified of the update.

NOTE: All of the installation methods described below require that the user performing the installation have administrator access to the Atlassian Cloud product (Jira, for example) to which the Forge app is attached.

Install to Staging

You’re the sole developer of the app, and you wish to install the Staging version of your app to your Atlassian Cloud test instance without going through setup of a CI/CD pipeline (we’ll do that later). Let’s run the forge install command [5] from your app’s root directory. Like forge deploy, forge install targets the Development environment by default, so we’ll need to specify Staging instead; the command accepts the -e staging argument just like forge deploy:

Install to Staging on Another Instance

You’ve tested your app on your own Atlassian Cloud site. For the purposes of real-world testing, now you wish to deploy it to another site that your company uses for all day-to-day Atlassian-based activities. What do you do?

Recall my discussion about required user permissions earlier. You’ll need to ask an administrator of the Atlassian Cloud site for your company to make your Atlassian Cloud user – the same user that created the app – a temporary administrator. Once that’s done, you’ll perform the same steps as you did in the Install to Staging section above.

Install a Limited-Release App to Production

You’ve tested in Staging extensively, and now you’re ready to install to the Production environment. You’ve already followed the steps described in Deploying Your Forge App above, but with Production as the target environment. You’ve considered distributing your app via the Atlassian Marketplace, which is the equivalent of Google’s Play Store or Apple’s App Store, but for apps that run in the Atlassian ecosystem. However, you don’t wish to make your app available yet in the Marketplace, but you do wish to distribute it to a set of beta customers. Let’s see how.

A Forge app can be shared using an installation link generated via the developer console. This allows the app to be distributed to other sites without using the Atlassian Marketplace. To generate installation links for your app, the following requirements must be met:

  • The app must not be a paid app.

  • The app must not have a license in its manifest.yml file.

  • The app must not have been submitted for listing in the Marketplace.[MB1] 

To generate an installation link for your app, let’s visit the list of apps in your Atlassian developer console [6]:

In our case, the app is called getting-started. It’s currently not shared, so we’ll need to enable sharing, then we can get an installation link:

Wait a minute. Atlassian is asking for some information before you can share your app:

You’re required to specify the following:

  • the company/department that produced the app

  • a link to the app’s customer support contact information

  • a link to the app’s privacy policy – check out [7] for more information

  • whether the app stores personal data

Once you fill those out with valid information, then click Save Changes, it’ll ask you the Atlassian Cloud products for which your app is intended, then you can generate an installation link:

You can then send the installation link to your customers. If a customer wishes to install the app to their Atlassian Cloud site, one of their Atlassian Cloud product or site administrators can visit the link.

Atlassian Marketplace

A Forge app can be listed in the Atlassian Marketplace, and customers can install it from there. The Marketplace gives you a way to advertise your app (whether free ­or paid) to all Atlassian Cloud customers. It’s also the only way to distribute a paid and/or licensed Forge app; the Marketplace handles customer subscriptions, billing, payments and related functions for your app. However, once you list your app in the Marketplace, you may no longer share your app via installation link. To see how to submit your app to the Marketplace listing approval process, visit Listing Forge Apps [8].[C(L1] 

Continuous Integration and Continuous Deployment for Your App

Now that we’ve explained manual deployments to you, you’re probably wondering, “How can I do all this stuff automatically via CI/CD?” How to Configure CI/CD for an Atlassian Forge App [9] has plenty of information on that front, using Bitbucket as the repository and CI/CD platform.[MB2] [C(L3] [C(L4] [C(L5] [AH6]  It’s actually fairly straightforward; let’s work on an example. By the way, this section assumes that you already have general knowledge of Bitbucket pipelines.

First, enable your pipelines. In your repository’s settings, on the left sidebar, click Settings in the Pipelines section:

Then, click Enable Pipelines:

The next thing to do is define repository variables for your Forge credentials. The Forge CLI commands that will be part of your CI/CD steps will automatically use those credentials to access and upload to the Forge environments, so that your pipelines don’t need to issue a forge login command. In your repository, on the left sidebar, click Repository Settings:

Then, in the Pipelines section of the left sidebar, click Repository Variables:

On the page that appears, add the following variables:

  • FORGE_EMAIL: The email address of the Forge user that has sufficient access to Bitbucket and Forge for the purposes of CI/CD.

  • FORGE_API_TOKEN: The API token defined for the above Forge user. Make it a secured/encrypted variable.

Now, let’s create a bitbucket-pipelines.yml in the root of your repository, and let’s define a few things within.

Getting Started with Forge [10] indicates that you must use an LTS version of Node 14, 16 or 18. At the top of the file, we’ll specify that we wish to use Node 18:


Now, let’s define a step for smoke testing. This step will run whenever changes are pushed to any code branch in the repository. It will install npm packages, build the front end, turn off usage analytics [11], install the Forge CLI (to make Forge CLI commands available), then run the Forge linter:

Next, let’s define a branches subsection for our pipelines section. We’ll add steps for building the code and deploying it to the development environment automatically whenever changes are pushed to the main code branch. We’re limiting these actions to the main branch for simplicity’s sake, and also to keep them from being executed whenever a change is pushed to just any branch, such as a branch for a specific feature that hasn’t been approved to be merged to main.

That’s it! The next time you push a branch to your Forge app repository, the smoke test pipeline will be run. The next time you merge to main, the pipeline to build and deploy to the development environment will be run automatically. Pretty cool!

Thank You!

We discussed quite a few details about Forge app distribution. I hope you found this post valuable on your journey to bring your Forge app ideas to the world!

References

Chris Low & Alex Howard

Chris Low is a Senior Consultant at Moser Consulting. For over twenty years, he has designed and developed software of varying complexity and for various industries.

Alex Howard has worked at Moser for over 8½  years, and serves as the App Service Tech Lead of full lifecycle solutions. In Alex's time at Moser, he has delivered modern, full-stack TypeScript applications to commercial clients of both small and large scale (exceeding $5M). He can, and tends to, perform most developer or developer-adjacent roles (architect, devops, etc.). In his time at Moser, Alex has demonstrated not only a knack for, but also an incessant drive to, learn new things rapidly and then disseminate that knowledge to his peers. Excitable for new technologies and hobbies in a way that can infect others, Alex truly loves his role here at Moser.

Previous

Developing a Jira App: Three Tips for Atlassian Forge App Development
Next

Developing a Jira App: Getting Started with Atlassian Forge