How to adopt Forge from Connect

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.

For a walk-through of the required steps, check out this video:

Part 1: Install prerequisites and prepare your app

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:

1. Installed the Forge CLI.

2. Logged in with your API token.

3. 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.

Part 2: Convert your descriptor to a manifest

Now that you've got Forge CLI and your Connect app running, you're ready to prepare your Forge manifest.

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.

1. You'll need to have two variables before you run our tool:

• type: either jira or confluence, depending on what product your app is for

• url : the URL of your production Connect descriptor - for example, https://website.com/path/to/descriptor.json

2. To convert your descriptor, in your Connect app directory, run:

1
2
npx connect-to-forge@latest --type <jira|confluence> --url https://website.com/path/to/descriptor.json

You should see some output similar to this:

1
2
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 manifest.yml file in the current directory, equivalent to your Connect descriptor. The Forge app ID can be found in manifest.yml as app.id.

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.

If you're using Atlassian Connect Spring Boot or Atlassian Connect Express, you'll still need to keep your old Connect descriptor in place.

Part 3: Register and deploy your app to Forge

Now that we have your Forge manifest, we're ready to register and deploy your app.

1. Run forge register. The prompts will ask you to name your app. We recommend you use the same name as your existing Connect app.

If you get a command not found error here, you may have missed installing Forge in Part 1.

2. To deploy your app, run the forge deploy command and follow the prompts.

Part 4: Install your app to your development site

You're now ready to replace your existing Connect app installation in your cloud development site. Before proceeding, ensure your cloud development site has an existing Connect installation with the same key.

1. Run forge install 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.

2. 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.

Part 5: Review and agree to the Forge terms and DPA

The Forge Data Processing Addendum (Forge DPA) is incorporated in the Forge Terms, which all Forge developers must comply with to use the Forge platform.

1. Fill in this form to accept the Forge terms and DPA

Next steps

Your Connect app now has Forge capabilities. From here, we'd recommend you:

• Update your setup to our suggested directory structure

• Re-use your translation files for Forge modules

• Understand the best way to develop with Connect and Forge together

• Start extending your app with Forge modules