# Forge App Installation ### 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. {% hint style="info" %} **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. {% endhint %} *** ### Prerequisites #### Atlassian Requirements * Atlassian account with access to your Jira Cloud instance * Jira Admin permissions (to install apps) * [Atlassian Developer account](https://developer.atlassian.com/) * 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](https://github.com/nvm-sh/nvm) (Node Version Manager), which makes it easy to install and switch between Node versions. **Install nvm:** ```bash curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash ``` Restart your terminal, then install Node.js: ```bash nvm install 18 nvm use 18 ``` Verify the installation: ```bash node -v npm -v ``` Once Node.js is installed, install the Forge CLI globally: ```bash 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: ```bash sudo apt-get install libsecret-1-0 libsecret-1-dev gnome-keyring ``` Before running `forge login`, start the keyring daemon: ```bash eval $(dbus-launch --sh-syntax) echo '' | gnome-keyring-daemon --unlock --components=secrets ``` {% hint style="info" %} **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. {% endhint %} *** #### 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 #### Option B: Download Archive *** ### 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 ``` {% hint style="warning" %} **Important:** Remove the existing app.id line from the bottom of manifest.yml. A new ID will be generated when you register your app. {% endhint %} #### Domain Pattern Rules | Pattern | Allowed | Example | | ------------------ | ------- | ------------------------------ | | Exact domain | Yes | | | Subdomain wildcard | Yes | https\://\*.company.com | | Path wildcard | No | \* | | All domains | No | https\://\* | | HTTP (non-HTTPS) | No | | *** ### 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. {% hint style="warning" %} **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. {% endhint %} *** 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](https://developer.atlassian.com/) 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 {% hint style="info" %} **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. {% endhint %} #### 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., ) 2. **API Key:** The API key displayed when Commander starts 3. Click **Test Connection** 4. Click **Save Settings** {% hint style="success" %} **Verification:** Open any Jira issue and look for the Keeper panel. Try a simple operation to confirm the connection works. {% endhint %} ### 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-` 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. {% hint style="info" %} **How to find your group name:** Atlassian automatically creates a default user group named `jira-users-` 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**. {% endhint %} {% hint style="info" %} **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. {% endhint %} *** #### **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 TypeRole requiredRestricted roles (won't work)
Service ManagementService Desk Team or AdministratorService Desk Customers
SoftwareMember or AdministratorViewer
BusinessMember or AdministratorViewer
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-` 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 {% hint style="warning" %} **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. {% endhint %} *** #### **Setup summary**
What to configureWhen it's neededWhere to setDo once?
Edit Issue permissionApp icon not visible (most common)Project Settings → Access → Space Permissions → Edit PermissionsYes, per project
Project roleUser can't access the project at allProject Settings → Access → People and accessYes, per project
Product licenseUser can't access Jira or only sees JSM portaladmin.atlassian.com → Directory → Groups → Apps tabYes, site-wide
{% hint style="success" %} **Recommended:** Configure all three at the **group level** using your site's default `jira-users-` 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. {% endhint %} *** ### Troubleshooting #### Test Connection Not Working {% hint style="danger" %} **Symptom:** Test Connection fails or times out, but curl works from your machine. {% endhint %} **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** {% hint style="danger" %} **Symptom:** Users can open and view Jira issues, but the Keeper app action icon does not appear on the issue panel. {% endhint %} **Cause:** The user's group is missing the **Edit Issue** permission. This is a [Jira platform requirement](https://community.developer.atlassian.com/t/users-can-only-choose-to-display-hide-addons-webpanel-if-they-have-the-edit-issue-permission/48723) — 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-`) 5. Click **Save** See **Step 6** for complete details. *** #### **User Cannot Access Project or See Issues** {% hint style="danger" %} **Symptom:** User cannot open the project or view any issues at all (not just the Keeper panel). {% endhint %} **Possible causes:**
CauseHow to checkSolution
Wrong project role (Customer/Viewer)Project Settings → Access → People and access → check user's roleChange to Service Desk Team (JSM) or Member (Software/Business)
No product licenseadmin.atlassian.com → Directory → Groups → select group → Apps tabClick Grant access and add the correct product with the right role
User only sees JSM portalUser has Customer role or Customer licenseChange to User (Agent) license and Service Desk Team role
See **Step 6** for complete details. *** #### **App Panel Not Loading After Clicking Icon** {% hint style="danger" %} **Symptom:** The app action icon is visible, but clicking it shows a blank panel, an error, or a loading spinner that never completes. {% endhint %} **Possible causes:**
CauseSolution
App consent not grantedA 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 requiredOrg admin approves the app at admin.atlassian.com → Security → App access policies
API URL or API Key not configuredNavigate to Jira Settings → Apps → Keeper and complete Step 5
Tunnel / Commander not runningStart the Commander service and ensure the tunnel is active
*** #### **Changes Not Taking Effect** {% hint style="danger" %} **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). {% endhint %} **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** {% hint style="danger" %} **Symptom:** The app doesn't appear anywhere — no icon on issues, no entry in Jira Settings → Apps. {% endhint %} **Possible causes:**
CauseSolution
App not installed on this siteRun forge install -e production or verify with forge installations list
App deployed to wrong environmentRun forge deploy -e production
Browser cacheClear 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 ``` {% hint style="info" %} Manifest permission changes take effect immediately after deploy. No reinstall required. {% endhint %} *** ### 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 {% code overflow="wrap" %} ``` 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 ``` {% endcode %} #### Manifest Domain Configuration {% code overflow="wrap" %} ``` permissions: external: fetch: backend: - address: https://your-custom-domain.com ``` {% endcode %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.keeper.io/en/keeperpam/secrets-manager/integrations/jira-workflow/forge-app-installation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.