Skip to content

Deploy The Jira Forge App

Overview

Create and install a customer-owned Atlassian Forge app for the self-hosted CloudAEye Code Review deployment. The app connects Jira Cloud to CloudAEye so that Code Review can receive Jira issue and sprint events, resolve Jira context, list projects, and create tracking issues.

This deployment model gives your organization ownership of the Forge app registration, environments, secrets, deployments, and Jira installations. Atlassian hosts the Forge functions, while the functions communicate with your CloudAEye endpoint over HTTPS.

Use this guide with the Jira Forge source bundle provided by CloudAEye for your self-hosted deployment.

See Atlassian's Getting started with Forge guide for Forge tooling reference.

Prerequisites

  • A Jira Cloud site. Forge apps cannot be installed on Jira Data Center or Jira Server.
  • Jira site administrator access for the final installation.
  • An Atlassian account that can register Forge apps.
  • The CloudAEye Jira Forge source bundle.
  • Node.js 24.x and npm.
  • A production CloudAEye Code Review endpoint reachable from Atlassian Forge over HTTPS.
  • The value of the server_x_api_key Terraform variable configured in the AWS ECS deployment guide. Use this same value for the Forge SERVER_API_KEY variable.

Complete the Self-Hosted Deployment Guide before installing the Jira app. The Jira app registers its installation and web trigger URLs with the CloudAEye backend during installation.

Step 1: Prepare The Source Bundle

Extract the CloudAEye Jira Forge source bundle provided to you, then open a terminal in the extracted directory.

Install the required dependencies:

npm ci

The included package-lock.json ensures that npm ci installs the dependency versions tested with the app.

Step 2: Configure The CloudAEye Endpoint

The Forge app must send requests to your self-hosted CloudAEye environment. From the extracted Terraform deployment directory, get the deployed application URL:

terraform output -raw app_base_url

The API_ENDPOINT Forge variable is required. The app reads the CloudAEye endpoint from this variable and cannot send installation or Jira event requests without it. Its value must be the URL returned by Terraform, followed by /external-service. Replace <app_base_url> with the exact Terraform output, without a trailing slash. The URL must use HTTPS and be publicly reachable because Atlassian runs Forge functions outside your VPC.

Next, update permissions.external.fetch.backend in manifest.yml. Add the same Terraform URL without the /external-service path:

permissions:
  external:
    fetch:
      backend:
        - "<app_base_url>"

Forge blocks outbound calls to origins that are not declared in the manifest. See Atlassian's Forge permissions reference.

Step 3: Install The Forge CLI And Sign In

Install the latest Forge CLI:

npm install --global @forge/cli@latest

Create an Atlassian API scoped token for the account that will own the app, then sign in:

forge login

Step 4: Register The Forge App

From the source bundle root, register a new app:

forge register "CloudAEye Code Review Jira - <company>"

Replace <company> with a short organization identifier. Forge creates a new app owned by the authenticated Atlassian account and replaces app.id in manifest.yml with the new app ARI.

After registration, verify that manifest.yml contains an app ID similar to:

app:
  id: ari:cloud:ecosystem::app/00000000-0000-0000-0000-000000000000

Run forge register only once for the production app.

The app appears in the Atlassian Developer Console after registration.

Step 5: Configure Production Variables

Configure the CloudAEye endpoint and shared authentication key:

Required Forge variable Purpose
API_ENDPOINT CloudAEye external service URL, including the /external-service path
SERVER_API_KEY Authenticates requests between the Forge app and CloudAEye

Store both values:

forge variables set --environment production API_ENDPOINT "<app_base_url>/external-service"
forge variables set --environment production SERVER_API_KEY "<server-api-key>"

Verify the variable names:

forge variables list --environment production

Step 6: Permissions

The following Jira scopes are needed:

Scope Why CloudAEye needs it
read:jira-work Read issues, comments, and Jira work data
write:jira-work Create tracking issues and write Jira work data
read:jira-user Resolve Jira users associated with issue activity
read:project:jira List and identify Jira projects

The app also declares outbound access to the on prem backend domain.

Step 7: Validate And Deploy

Run Forge validation from the source bundle root:

forge lint

Resolve all errors before deployment. Then deploy the app to production:

forge deploy --environment production

Deploying after setting the variables is required. Forge uses the variable values captured by the most recent deployment to that environment.

Both API_ENDPOINT and SERVER_API_KEY must be set for the same Forge environment used by forge deploy and forge install.

In the Atlassian Developer Console, open the app and confirm:

  • The production environment has a successful deployment.
  • The displayed app ID matches manifest.yml.
  • The Jira scopes match the reviewed list.
  • The external egress origin is the intended origin.

Step 8: Install The App On Jira

Now that the app is published, it is time to install it.

forge install \
  --environment production \
  --product jira \
  --site <company>.atlassian.net

During installation, the app:

  1. Resolves the Jira site and installation context.
  2. Generates the web trigger URLs required by the CloudAEye integration.
  3. Sends the installation metadata and web trigger URLs to the configured CloudAEye endpoint.

List the installations associated with the app:

forge install list

Troubleshooting

Registration Or Deployment Fails

Check:

  • forge whoami shows the intended organization-controlled account.
  • The Forge CLI is current.
  • npm ci completed successfully.
  • The command is running from the directory containing manifest.yml.
  • The app ID in manifest.yml belongs to the authenticated Forge account.
  • forge lint completes without errors.

If registration did not complete, run forge register once. Do not register again when manifest.yml already contains the app ID used by your production installation.

Jira Installation Fails

Check:

  • The target is a Jira Cloud site.
  • The installing user is a Jira site administrator.
  • The production deployment completed successfully.
  • The --site value uses the <company>.atlassian.net hostname.
  • The administrator approved every requested scope and egress permission.

Jira Events Do Not Reach CloudAEye

Check:

  • The app remains installed under Jira Connected apps.
  • The Jira project is enabled in the CloudAEye integration settings.
  • SERVER_API_KEY is valid.
  • The app installation and backend tenant record refer to the same Jira site name.

Use the app's Monitoring, Logs, and Installations pages in the Atlassian Developer Console.

Uninstall The App

To remove the app from a Jira site:

forge uninstall \
  --environment production \
  --product jira \
  --site <company>.atlassian.net

Then:

  1. Confirm the app no longer appears under Jira Connected apps.
  2. Delete the Jira integration in CloudAEye.
  3. Confirm that the Jira integration is no longer active in CloudAEye.