Forge App Installation

Deploy your own Keeper for Jira Forge app for Workflow Approvals

Overview

Atlassian Forge apps have strict security controls on outbound network requests. The app's manifest.yml must explicitly allow all external domains the app can communicate with.

Why self-hosted deployment?

Each customer must deploy their own Forge app with their specific Commander API domain allowlisted. This ensures secure, isolated connectivity to your infrastructure.

---

Prerequisites

Atlassian Requirements

• Atlassian account with access to your Jira Cloud instance

• Jira Admin permissions (to install apps)

• Atlassian Developer account

• Node.js 18+ installed

• Forge CLI installed: npm install -g @forge/cli

Node.js Setup (via nvm)

The Forge CLI requires Node.js 18+. We recommend installing Node.js using nvm (Node Version Manager), which makes it easy to install and switch between Node versions.

Install nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Restart your terminal, then install Node.js:

nvm install 18
nvm use 18

Verify the installation:

node -v
npm -v

Once Node.js is installed, install the Forge CLI globally:

npm install -g @forge/cli

---

WSL / Linux Requirements

On WSL or Linux environments without a desktop, forge login requires additional packages to securely store credentials. The Forge CLI uses libsecret to access the OS keychain, which is not available by default on headless Linux.

Install the required packages:

sudo apt-get install libsecret-1-0 libsecret-1-dev gnome-keyring

Before running forge login, start the keyring daemon:

eval $(dbus-launch --sh-syntax)
echo '' | gnome-keyring-daemon --unlock --components=secrets

Why is this needed?

The Forge CLI stores your Atlassian API token using the OS secret service. On macOS (Keychain) and Windows (Credential Manager) this is built in. On Linux/WSL, you must install libsecret (the client library) and gnome-keyring (the keyring daemon) manually.

---

Keeper Requirements

• Keeper Enterprise account with Commander CLI access

• Commander CLI version 17.1.7 or later

• Commander CLI configured with persistent login

• Secure tunnel exposing Commander API

---

Step 1: Get the Source Code

Option A: Clone Repository

https://github.com/Keeper-Security/jira-connector-hub

Option B: Download Archive

https://github.com/Keeper-Security/jira-connector-hub/archive/refs/heads/main.zip

---

Step 2: Configure Your Domain

Open manifest.yml and add your Commander Service Mode domain to the permissions.external.fetch.backend section:

permissions:
  scopes:
      - read:jira-work
      - write:jira-work
      - storage:app
      - read:jira-user
  external:
      fetch:
        backend:
            # ADD YOUR DOMAIN(S) BELOW
            - address: https://keeper-api.yourcompany.com
            # Or use subdomain wildcard:
            - address: https://*.yourcompany.com

Important: Remove the existing app.id line from the bottom of manifest.yml. A new ID will be generated when you register your app.

Domain Pattern Rules

Pattern	Allowed	Example
Exact domain	Yes	https://api.company.com
Subdomain wildcard	Yes	https://*.company.com
Path wildcard	No	https://api.company.com/*
All domains	No	https://*
HTTP (non-HTTPS)	No	http://api.company.com

---

Step 3: Build the Application

# Install root dependencies
npm install

# Build Global Page UI
cd static/keeper-ui
npm install
npm run build
cd ../..

# Build Issue Panel UI
cd static/keeper-issue-ui
npm install
npm run build
cd ../..

---

Step 4: Deploy to Atlassian

Authenticate

forge login

Follow the browser prompts to authenticate.

Register Your App

forge register

Enter an app name when prompted (e.g., Keeper for Jira - YourCompany).

Deploy

forge deploy -e production

Install on Jira

forge install -e production

When prompted:

1. Select Jira as the product

2. Enter your Jira site (e.g., yourcompany.atlassian.net)

3. Confirm installation

Grant App Access (After Installation)

After installing the app with forge install, navigate to Jira Settings → Apps → Keeper. On first load, you will see a prompt:

Click Allow access to grant the required permissions. This is a one-time OAuth consent step that authorizes the Forge app to interact with your Jira instance.

Note: If you skip this step, the Keeper app panels and configuration page will not load. Each user who accesses the app for the first time will need to grant access individually.

---

If a non-owner user clicks Allow access and sees:

This means the Forge app has not been shared yet. By default, Forge apps in development mode are restricted to the app owner only (the person who ran forge register).

To resolve this, the app owner must enable sharing:

1. Go to Atlassian Developer Console

2. Select the Keeper for Jira app

3. Navigate to Distribution → Sharing

4. Toggle Share app to enabled

5. Copy the installation link and share it with other Jira admins or users

Note: This step is required for any user other than the app owner to access the app. Once sharing is enabled, all users on the installed Jira site can grant access and use the app.

Multi-Site Installation (Optional)

If you need to install the app on multiple Jira sites or allow other administrators to install:

1. Go to Atlassian Developer Console

2. Select your newly registered Keeper app

3. Navigate to Distribution → Sharing

4. Toggle Share app to enabled

5. Copy the installation link

6. Share the link with other Jira admins or use it to install on additional sites

---

Step 5: Configure in Jira

1. Navigate to Jira Settings → Apps → Keeper

2. On the Configuration tab, enter:

   1. API URL: Your Commander API URL (e.g., https://keeper-api.yourcompany.com/api/v2)

   2. API Key: The API key displayed when Commander starts

3. Click Test Connection

4. Click Save Settings

Verification: Open any Jira issue and look for the Keeper panel. Try a simple operation to confirm the connection works.

Step 6: Configure User Access

After the app is installed and configured, you may need to configure Jira permissions so that users can see and interact with the Keeper app panel on issues.

---

Keeper app action icon not visible on the issue panel

This is the most common issue after installation. The Keeper app icon (which opens the app panel) only appears for users who have the Edit Issue permission. This is a Jira platform requirement that applies to all app panels — not specific to Keeper.

To fix this:

1. Go to Project Settings → Access → Space Permissions

2. Click the gear icon (Edit Permissions)

3. Under Issue Permissions, find "Edit Issue"

4. Add your site's default Jira users group: jira-users-<your-site-name>

5. Click Save

This is a one-time setup per project. All users in the group will immediately be able to see the Keeper app icon on issues.

How to find your group name: Atlassian automatically creates a default user group named jira-users-<your-site-name> when your Jira site is provisioned. For example:

• Site acme.atlassian.net → group is jira-users-acme

• Site bigcorp.atlassian.net → group is jira-users-bigcorp

You can verify your group names at admin.atlassian.com → select your organization → Directory → Groups.

Why is this needed? Jira requires the EDIT_ISSUE permission for users to display or interact with app panels on issues. The Keeper app uses a Forge jira:issuePanel module — without the Edit Issue permission, the app action icon is hidden from the issue view.

---

User cannot access the project or see issues at all

If a user cannot open the project or view any issues (not just the Keeper panel), the issue is broader than app permissions. Check the following:

1. Verify the user has the correct project role

Restricted roles like Customer or Viewer do not provide full issue access.

Project Type	Role required	Restricted roles (won't work)
Service Management	Service Desk Team or Administrator	Service Desk Customers
Software	Member or Administrator	Viewer
Business	Member or Administrator	Viewer

To check or change a role:

1. Go to Project Settings → Access → People and access

2. Find the user or group and verify the role

3. Change restricted roles to one that provides full issue access

2. Verify the user has a product license

A project role alone is not sufficient — the user also needs an active product license.

1. Go to admin.atlassian.com → select your organization

2. Click Directory → Groups

3. Find your default Jira users group: jira-users-<your-site-name>

4. Click on the group, then go to the Apps tab

5. Check which products are listed and their roles:

   • Jira → Role should be User

   • Jira Service Management → Role should be User (Agent), not Customer

6. If a required product is missing, click Grant access (top right), select the product, and assign the correct role

Customer vs. Agent: In Jira Service Management, the Customer role only provides access to the self-service portal. Customers cannot see the full Jira issue view where the Keeper app panel renders. Ensure the role is set to User (Agent), not Customer.

---

Setup summary

What to configure	When it's needed	Where to set	Do once?
Edit Issue permission	App icon not visible (most common)	Project Settings → Access → Space Permissions → Edit Permissions	Yes, per project
Project role	User can't access the project at all	Project Settings → Access → People and access	Yes, per project
Product license	User can't access Jira or only sees JSM portal	admin.atlassian.com → Directory → Groups → Apps tab	Yes, site-wide

Recommended: Configure all three at the group level using your site's default jira-users-<your-site-name> group. This way, new users only need to be added to the group — no additional per-user or per-project configuration is required. The app consent ("Allow access") is handled once by the admin during Step 4.

---

Troubleshooting

Test Connection Not Working

Symptom: Test Connection fails or times out, but curl works from your machine.

Cause: Your domain is not allowed in manifest.yml.

Solution:

1. Add your domain to permissions.external.fetch.backend

2. Run forge deploy -e production

3. Retry Test Connection (no reinstall needed)

---

Network Errors

Possible causes:

Issue	Solution
Domain not whitelisted	Add to manifest, redeploy
Using HTTP instead of HTTPS	Forge requires HTTPS only
Self-signed certificate	Use a valid SSL certificate
Tunnel not running	Start Commander service

---

App Action Icon Not Visible on Issue Panel

Symptom: Users can open and view Jira issues, but the Keeper app action icon does not appear on the issue panel.

Cause: The user's group is missing the Edit Issue permission. This is a Jira platform requirement — app panel icons are only shown to users with the EDIT_ISSUE permission.

Solution:

1. Go to Project Settings → Access → Space Permissions

2. Click the gear icon (Edit Permissions)

3. Under Issue Permissions, find "Edit Issue"

4. Add the user's group (e.g., jira-users-<your-site-name>)

5. Click Save

See Step 6 for complete details.

---

User Cannot Access Project or See Issues

Symptom: User cannot open the project or view any issues at all (not just the Keeper panel).

Possible causes:

Cause	How to check	Solution
Wrong project role (Customer/Viewer)	Project Settings → Access → People and access → check user's role	Change to Service Desk Team (JSM) or Member (Software/Business)
No product license	admin.atlassian.com → Directory → Groups → select group → Apps tab	Click Grant access and add the correct product with the right role
User only sees JSM portal	User has Customer role or Customer license	Change to User (Agent) license and Service Desk Team role

See Step 6 for complete details.

---

App Panel Not Loading After Clicking Icon

Symptom: The app action icon is visible, but clicking it shows a blank panel, an error, or a loading spinner that never completes.

Possible causes:

Cause	Solution
App consent not granted	A Jira admin should navigate to Jira Settings → Apps → Keeper and click Allow access (see Step 4)
App not shared (dev mode)	App owner enables sharing in Developer Console → Distribution → Sharing
Org-level app approval required	Org admin approves the app at admin.atlassian.com → Security → App access policies
API URL or API Key not configured	Navigate to Jira Settings → Apps → Keeper and complete Step 5
Tunnel / Commander not running	Start the Commander service and ensure the tunnel is active

---

Changes Not Taking Effect

Symptom: After changing permissions or roles, the user still sees the old behavior (e.g., app icon still visible after removing Edit Issue, or still not visible after granting it).

Cause: Jira caches permissions. Changes may take a few minutes to propagate.

Solution:

1. Have the user log out of Jira and log back in

2. Hard refresh the page (Ctrl+Shift+R / Cmd+Shift+R)

3. Or open the issue in an incognito/private browser window

---

App Not Appearing at All

Symptom: The app doesn't appear anywhere — no icon on issues, no entry in Jira Settings → Apps.

Possible causes:

Cause	Solution
App not installed on this site	Run forge install -e production or verify with forge installations list
App deployed to wrong environment	Run forge deploy -e production
Browser cache	Clear browser cache and hard refresh, or try incognito window

---

Updating Your Deployment

When a new version is released:

# Get latest code
git pull origin main

# Rebuild UI
cd static/keeper-ui && npm run build && cd ../..
cd static/keeper-issue-ui && npm run build && cd ../..

# Deploy
forge deploy -e production

Manifest permission changes take effect immediately after deploy. No reinstall required.

---

Environment Management

Environment	Deploy Command	Install Command
Production	forge deploy -e production	forge install -e production

Useful Commands

# List installations
forge installations list

# View logs
forge logs

# Uninstall
forge uninstall

---

Security Best Practices

API Key Protection

• API keys are stored in Forge's encrypted app storage

• Never commit API keys to source control

• Rotate API keys periodically

Network Security

• All traffic uses HTTPS encryption

• Consider IP allowlisting on your firewall

• Use Cloudflare Access for additional authentication

Least Privilege

Configure Commander with only the required commands, for example:

  keeper service-create \
    -p=9009 \
    -c="record-add,list,ls,get,record-type-info,record-update,share-record,share-folder,rti,record-permission,epm,service-status" \
    -rm="foreground" \
    -q=y \
    -f=json

---

Quick Reference

Full Deployment Sequence

npm install
cd static/keeper-ui && npm install && npm run build && cd ../..
cd static/keeper-issue-ui && npm install && npm run build && cd ../..
forge login
forge register
forge deploy -e production
forge install -e production

Manifest Domain Configuration

permissions:
  external:
    fetch:
      backend:
        - address: https://your-custom-domain.com