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, 并且你想通过在该实例上安装Forge应用程序来在现实世界中测试它. 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:

  • 开发:这种环境最适合应用程序的开发和测试周期. 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.

  • 生产:当然，这是客户使用应用程序的环境.

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:

 

正如应用名称右侧的标签所暗示的那样，第二个是开发，第三个是分期. Production, the first one, doesn’t have such a tag.

注:所有应用在生产中的使用将受到Forge平台配额和限制。[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, 只有一个Atlassian Cloud用户可以执行部署和安装一个给定的Forge应用程序-即, the user who created the app. 当您考虑可能希望在一个Atlassian Cloud站点上执行开发时，这一点非常重要, then have other users test your app on a different site. 当然，这也让多个开发者开发同一款应用变得更加困难. On top of that, if someone leaves a company, and if they had created any Forge apps during their time at the company, 那么他们的Atlassian Cloud用户可能仍然需要拥有足够的特权来保持应用程序的可部署性.

Atlassian在他们的路线图上有一些东西，可以让多个用户“拥有”同一款应用，用于开发目的。[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, 现在您希望将其部署到Staging环境中，以便其他人进一步测试. Let’s do that.

Deploying Your Forge App

In Forge terminology, deployment 指的是在Forge环境中构建和部署特定版本的Forge应用程序. 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 指在Atlassian站点上安装特定的Forge环境-应用程序组合, presuming that the app has been deployed to the specified environment. Whenever a given app is updated via a deployment, 在所有Atlassian Cloud站点上，该应用程序在部署到环境中的所有安装都将收到更新通知.

注意:下面描述的所有安装方法都要求执行安装的用户具有对Atlassian Cloud产品(Jira)的管理员访问权限, for example) to which the Forge app is attached.

Install to Staging

You’re the sole developer of the app, 并且您希望将应用程序的Staging版本安装到Atlassian Cloud测试实例中，而不需要设置CI/CD管道(mg官方游戏中心稍后会这样做)。. 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, 现在，您希望将其部署到公司用于所有基于atlassian的日常活动的另一个站点. What do you do?

Recall my discussion about required user permissions earlier. 您需要请求Atlassian Cloud站点的管理员为您的公司将您的Atlassian Cloud用户(创建应用程序的同一用户)设置为临时管理员. 完成后，您将执行与前面安装到暂存一节中相同的步骤.

Install a Limited-Release App to Production

您已经在登台环境中进行了广泛的测试，现在可以安装到生产环境了. 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.

Forge应用程序可以通过开发者控制台生成的安装链接共享. 这使得应用程序可以在不使用Atlassian Marketplace的情况下发布到其他网站. 要为应用程序生成安装链接，必须满足以下要求:

  • 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. 它目前没有被共享，所以mg官方游戏中心需要启用共享，然后mg官方游戏中心可以得到一个安装链接:

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

Forge应用程序可以在Atlassian Marketplace上列出，用户可以从那里安装它. 该市场为你提供了一种向所有Atlassian Cloud客户宣传应用(无论是免费还是付费)的方式. 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 部署时，您可能想知道，“我如何通过CI/CD自动完成所有这些工作??“如何为Atlassian Forge应用程序配置CI/CD[9]在这方面有很多信息, 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. 顺便说一下，本节假设您已经具备Bitbucket管道的一般知识.

First, enable your pipelines. 在存储库的设置中，在左侧栏中，单击管道部分的设置:

Then, click Enable Pipelines:

The next thing to do is define repository variables for your Forge credentials. Forge CLI命令将成为您的CI/CD步骤的一部分，它将自动使用这些凭证来访问和上传Forge环境, 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:用于CI/CD目的的对Bitbucket和Forge有足够访问权限的Forge用户的电子邮件地址.

  • 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]表明您必须使用Node 14、16或18的LTS版本. 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. mg官方游戏中心将添加构建代码并将其自动部署到开发环境的步骤 main code branch. We’re limiting these actions to the main branch for simplicity’s sake, 同时也防止它们在任何更改被推送到任何分支时被执行, such as a branch for a specific feature that hasn’t been approved to be merged to main.

That’s it! 下次将分支推送到Forge应用程序存储库时，将运行冒烟测试管道. The next time you merge to main，构建和部署到开发环境的管道将自动运行. Pretty cool!

Thank You!

We discussed quite a few details about Forge app distribution. 我希望你发现这篇文章在你的旅程中有价值，把你的Forge应用程序的想法带给世界!

References

Chris Low & Alex Howard

Chris Low is a Senior Consultant at Moser Consulting. For over twenty years, 他为不同的行业设计和开发了不同复杂性的软件.

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, 面向小型和大型商业客户(超过500万美元)的全栈TypeScript应用程序. 他可以，而且倾向于，扮演大多数开发人员或与开发人员相邻的角色(架构师、开发人员等).). 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