Forge allows developers to build highly requested app features using extension points like custom fields and UI modifications in Jira. But for apps on Connect today, incorporating these Forge-only features has been challenging. Some partners have had to build Forge companion apps that install alongside the main Connect app, which creates more work for partners and a less intuitive experience for customers.
Today, we're excited to announce that partners can now adopt Forge features within their existing Connect apps, eliminating the need to build a companion app or completely rewrite the app on Forge. This will enable Connect builders to access a wider array of capabilities, continue to get the best the Atlassian platform has to offer, and create more seamless experiences for customers.
An equally important aspect of this process is that it is incremental, meaning Forge modules can be added in stages, and with the new tooling we've just released, adding the first new Forge module takes less than an hour. Using the automated CLI tool, developers can convert their Connect descriptor to a Forge manifest with a single command. After some quick set-up, they can begin adding new Forge modules.
Since we began working with our pilot group, over 100 Connect apps have started to use Forge features, and we're excited to make it available to the wider community. As Forge continues to gain new capabilities, we want all apps to have access to the best Forge has to offer.
We have been working on our first gradual steps towards Forge adoption in one of our Connect apps. With the new CLI tooling and Atlassian's outstanding support, we have confidence that we are moving in the right direction.
Tobias Binna, Toolsplus
Becoming a Forge app: key concepts
Let's start with a quick overview of the process (or you can skip right to the docs). There are a few preparation steps you'll need to take before your Connect app can start to use Forge modules: create a Forge manifest, register, deploy, and install. This process does not impact or override your existing Connect app.
- Convert your Connect descriptor to a Forge manifest, using the automated tool.
manifest.ymlis the Forge equivalent of the Connect descriptor.json file. We provide a CLI tool that automatically converts your Connect descriptor to the Forge manifest. - Register your app as a Forge app, using the
forge registercommand. This step allows us to recognize your app as a Forge app when it's later deployed and installed. - Finally, use the Forge CLI to deploy it to the Forge environment and install it in your development site. The app is now installed in your test site as a Forge app.
Meanwhile, the Connect version of your app is still unchanged and accessible on the Marketplace. After you've added one or more Forge modules to your app and tested to ensure things work as expected, you can list a Forge successor to your Connect Marketplace listing, which preserves your existing listing and carries over all reviews and installs. When your customers upgrade, or when a new customer installs, they'll get the version of your app containing the new Forge modules.
Which apps can start to adopt Forge?
While our analysis shows the majority of Connect apps can start to adopt Forge, it's important to be aware that Connect apps using certain features, as well as Bitbucket Connect apps, won't be able to try adopting Forge just yet. Check the docs to determine whether your app is eligible and read up on the need-to-knows. We also recommend watching the linked Jira issues on the Limitations and differences page so you can stay updated as blockers are removed from the list.
Getting started
The process of adopting Forge can be broken down into incremental steps, which makes it easy to test and experiment. You can try just registering your app, adding a single module, or multiple modules. You can also go further and use your Connect app as a remote backend for a Forge app – see the Atlassian Connect Express (ACE) README or Atlassian Connect Spring Boot (ACSB) README for details. Along the way, you'll be able to test your app in development and staging to QA the new additions.
If you're ready to jump in and give it a try, you can begin by following the Getting Started guide. We also recommend bookmarking our reference guide to Connect and Forge module equivalents and reading up on best practices for developing on Forge and Connect at the same time.
Click through below to see a demo of the end-to-end process of adding a Forge module to a Connect app, and follow along in the demo app.
Next steps
We invite you to give the process a try, and let us know if you have feedback or questions by posting in the developer community – we'll be actively monitoring the space. We'll also be hosting an Atlassian Community Event session in the coming weeks, where we'll walk through a live demo and take your questions. You can sign up for whichever time works better for you: the A session (optimized for Europe), or the B session (optimized for the US). The content will be the same for both broadcasts. Hope to see you there!