This guide will take you through the steps of adopting Forge for your Connect app, and replacing your installed app on your cloud development site.
Follow Getting started for step-by-step instructions to set up your Forge development environment and development site.
Once you've completed this, you should now have:
Installed the Forge CLI.
Logged in with your API token.
Accessed your cloud developer site to test on (this can be the same as your Connect testing environment).
Install your Connect app into your cloud developer site, so that you can test it as you adopt Forge.
Now that you've got Forge CLI and your Connect app running, you're ready to prepare your Forge manifest.
In Connect, you're used to working with a descriptor file () that describes your app.
In Forge, that equivalent file is declared as YAML and is called a Forge manifest (). It sits at the base of your app directory.
Although the file type is different, the declarations are very similar. So we've built a tool to automatically convert your existing descriptor to a manifest.
: either or , depending on what product your app is for
: the URL of your production connect manifest - for example,
npx connect-to-forge@latest --type <jira|confluence> --url https://website.com/path/to/descriptor.json
You should see some output similar to this:
Conversion begun for 'Existing Connect App': - Moved all lifecycle events into connectModules.confluence:lifecycle. - Moved 5 modules into connectModules in the Manifest - Converted 3 connect scopes into correct format in manifest. Forge manifest generated and saved to manifest.yml
This will create your Forge manifest: a file in the current directory, equivalent to your Connect descriptor.
At this stage, we would suggest creating a new branch of your Connect application in your local development environment and committing your newly created manifest into your repository.
Now that we have your Forge manifest, we're ready to register and deploy your app.
If you get a error here, you may have missed installing Forge in Part 1.
Your Forge app now has three environments by default: , , and , and each should have its own Connect key. There is no automated way (yet) of handling these.
See Handling app keys for more information.
You're now ready to replace your existing connect app installation in your cloud development site.
Run and follow the prompts to target your development site. The sync process will note the matching keys and replace your Connect app with the Forge app.
You can now visit your test site to inspect and test your app. Within Apps > Manage apps, you'll be able to see your Forge app installed.
Your Connect app now has Forge capabilities. From here, we'd recommend you:
Update your setup to our suggested directory structure
Understand the best way to develop with Connect and Forge together
We'd love any feedback you have on this process through the Adopting Forge from Connect category on the Atlassian Developer Community.
Rate this page: