Build AGC-compatible Forge apps

Introduction

As part of the Atlassian Government Cloud (AGC) initiative, if you want your Forge apps to be available to our AGC customers, you'll first need to make your apps AGC-compatible. This tutorial will walk you through building an AGC-compatible Forge app.

You can either make your existing Forge apps AGC-compatible or create a new AGC-compatible Forge app from scratch. The difference between making an existing app and a brand-new app AGC-compatible is explained in the Create your app section.

Note that some instructions in this tutorial are workarounds. The Forge CLI is still under development for a better AGC experience.

Prerequisites

In order to manage your apps, you'll use the Forge CLI. There is no AGC-specific version of the Forge CLI, you'll use the same Forge CLI as for standard cloud Forge apps. You need to:

• Set up Node.js
• Install the latest version of Forge CLI

Also, you need to create an AGC account and obtain a test site: Get access to AGC.

Create an API token

In order to use the Forge CLI on AGC, you'll need an API token that is created inside AGC.

1. Go to https://id.atlassian-us-gov-mod.com/manage/api-tokens.
2. Click Create API token.
3. Enter a label to describe your API token. For example, forge-agc-api-token.
4. Click Create.
5. Click Copy to clipboard and close the dialog. Save the token in a safe place.

Override Forge CLI's API endpoint

In order to use the Forge CLI for AGC, you'll need to override an environment variable.

1
2
export FORGE_GRAPHQL_GATEWAY=https://api.atlassian-us-gov-mod.com/graphql

Make a Forge app AGC-compatible

If you've built a Forge app before, you'll notice that the process for creating an AGC-compatible Forge app is largely similar. You may even notice that this tutorial has many similarities with our Build your first app tutorial.

Before we delve into the specifics, it's essential to clarify one key point. If you already have a Forge app in our standard cloud environment, there's no need to rewrite your application. Essentially, you'll be deploying the same app and code onto AGC.

Log in with the API token

This is similar to the standard cloud experience.

1. Start the process by running:

   1
   2
   forge login
   

2. Enter the email address associated with your AGC account.

3. Enter your AGC API token.

4. You'll see a message confirming you are logged in:

   1
   2
   ✔ Logged in as John Doe.
   

1
2
export FORGE_GRAPHQL_GATEWAY=https://api.atlassian.com/graphql
forge login

Create your app

You may create an AGC-compatible app by registering an existing app or creating a new one from scratch.

Register an existing Forge app as AGC-compatible

Follow these steps if you already have a Forge app in our standard cloud systems and want to make it AGC-compatible.

1. First, you need to give a new app ID to your AGC-compatible app. Comment out the standard cloud app ID and add a new id attribute with a different UUID to your app's manifest.yml file. It should look like this:

   1
   2
   app:
   # id: ari:cloud:ecosystem::app/5c3ed5a5-721d-4fb8-b283-a3e22ec28d0a # Standard cloud app ID
   id: ari:cloud:ecosystem::app/b8703e30-dff5-409e-a0c1-cf4a6aa5e7f0 # AGC app ID
   

2. Register your app by running:

   1
   2
   forge register
   

3. Enter a name for your app (up to 50 characters), for example my-agc-app.

4. Change to the app subdirectory to see the app files:

   1
   2
   cd my-agc-app
   

   You'll see a message indicating now your app is now registered in AGC.

   1
   2
   ✔ Registered my-agc-app
   

1
2
app:
  id: ari:cloud:ecosystem::app/5c3ed5a5-721d-4fb8-b283-a3e22ec28d0a # Standard cloud app ID

perimeterOverrides:
  fedramp-moderate:
    app:
      id: ari:cloud:ecosystem::app/b8703e30-dff5-409e-a0c1-cf4a6aa5e7f0 # AGC app ID

Create an AGC-compatible Forge app from scratch

This process is the same as creating an app in our standard cloud systems.

1. Navigate to the directory where you want to create the app. A new subdirectory with the app's name will be created there.

2. Create your app by running:

   1
   2
   forge create
   

3. Enter a name for your app (up to 50 characters). For example, my-agc-app.

4. Select the UI Kit category.

5. Select the Confluence product.

6. Select the confluence-macro template.

7. Change to the app subdirectory to see the app files:

   1
   2
   cd my-agc-app
   

The template you get will be the same as for a standard cloud app.

Deploy and install your app

This is the same as the standard cloud experience.

1. Navigate to the app's top-level directory and deploy your app by running:

   1
   2
   forge deploy
   

2. Install your app by running:

   1
   2
   forge install
   

3. Select Confluence using the arrow keys and press the enter key.
4. Enter the domain name for your test site. For example, example.atlassian-us-gov-mod.net.

Similar to the standard cloud perimeter, you can deploy and install your AGC-compatible apps into development, staging or production environments with the -e or --environment parameter, for example:

1
2
forge deploy -e staging

View your app

This is also the same as the standard cloud experience.

1. Edit a Confluence page in your test site.

2. Type /.

3. Find the macro app by name (my-agc-app) in the menu that appears and select it.

4. Publish the page. Your app is now installed on your development site. The app should display on the page like so:

   

Test/debug your app

For daily development tasks, we highly recommend using our standard cloud environment, as the forge tunnel feature is unavailable in AGC. This approach offers a smoother and more efficient development process. Once your app is ready, you can proceed to deploy, install, and test it in AGC.

While we do not anticipate any issues, if you encounter problems in AGC that do not occur in the standard cloud environment, we suggest adding console.log statements to your code. You can then utilize the forge logs command or the AGC developer console to diagnose the situation.

As always, please don't hesitate to reach out to our support team whenever you need assistance.

View your app in the AGC developer console

You can view your AGC-compatible apps in the AGC developer console: https://developer.atlassian-us-gov-mod.com/console.

This console only shows your AGC-compatible apps. Similarly, you won`t see your AGC-compatible apps in your standard cloud developer console (https://developer.atlassian.com/console).

Once your app is deployed, it will appear in the AGC developer console. It offers the same user experience as the standard cloud developer console.

Distribute your app

See Distribute AGC-compatible Forge apps.

FAQ

Do I need to maintain a separate code base/branch?

No. Until we update the manifest file format to add support for perimeterOverrides, you'll need to comment and uncomment app IDs. When it comes to code, you should maintain a single code base for apps that are deployed in both standard cloud and AGC environments.

Do I need to obtain a FedRAMP ATO authorization?

No. Marketplace partners aren't expected to obtain a FedRAMP ATO authorization.

Do I need to deploy my app to the standard cloud environment first?

No, but we recommend you do so for development purposes. A Forge app can be deployed to the standard cloud environment, AGC, or both. However, since forge tunnel isn't available in AGC, we recommend that you deploy your app's development version into the standard cloud perimeter and do your daily development there. Once you've tested your app in standard cloud, you can deploy it to AGC.