[Forge] Custom UI app deployed, but still no link in the Jira avatar menu

RoieGolst · July 2, 2025, 10:40am

Hi everyone,

Environment


Product	Jira Cloud
Framework	Forge (Custom UI + a UI-Kit global page)
Forge CLI	12.0.0
Node	v22.12.0

What I’m trying to achieve

Add an item to the avatar/profile drop-down (under Theme, Switch account, etc.) that simply redirects to my existing global page.

I’m using the preview jira:personalSettingsPage module because the docs say it should place an entry in that menu and accept a viewportSize property. developer.atlassian.com

Manifest excerpt (minimal repro)

modules:
  jira:personalSettingsPage:
    - key: avatar-app
      resource: app-resource
      resolver:
        function: noop
      title: Out-of-Office Assistant
      viewportSize: small        # <- causes lint error
resources:
  - key: app-resource
    path: static/app/build
function:
  - key: noop
    handler: index.noop

Symptoms

Lint error

11:2  error  jira:personalSettingsPage should NOT have additional property 'viewportSize'  valid-document-required

If I remove viewportSize, the app deploys without lint errors, but nothing appears in the avatar menu (so users still can’t launch the page).

Steps to reproduce

Create a new Forge app (Custom UI).
Add the manifest snippet above.
Run forge lint → error appears.
Remove viewportSize, run forge deploy, and open Jira → no menu item in the profile menu.

What I’ve tried so far

Upgrading Forge CLI again (npm i -g @forge/cli) – still on 12.0.0
Different viewportSize values (medium, large, etc.)
Setting an icon field
Checking for any feature-flag/preview setting in the docs but couldn’t find one

Questions

Is viewportSize actually supported for jira:personalSettingsPage, or is the CLI schema out of date?
Do I need to opt-in to a preview flag or use a newer CLI/channel to get this module working?
Does anyone have a working manifest snippet that shows up in the avatar menu with Custom UI?

Any pointers would be greatly appreciated. Thanks!