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

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

• Node.js 18+ installed

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

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.

---

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 Not Appearing

1. Clear browser cache and refresh

2. Verify installation: forge installations list

3. Check deployment: forge deploy -e production

---

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