App Manifest

Last modified: 11 March 2025

Each app package must include a manifest.json file at the root of the package directory. The manifest file provides general information about the app, such as the name, description, and the list of modules contained in the app.

Sample Manifest

Here is sample manifest for an app:

{
 {...}
{
  "$schema": "https://json.schemastore.org/youtrack-app.json",
  "name" : "sample-app",
  "title" : "Sample App",
  "description" : "App description",
  "version": "1.0.0",
  "url": "https://github.com/example/youtrack-app",
  "icon": "icon.svg",
  "iconDark": "icon.svg",
  "minYouTrackVersion": "2022.2.0",
  "maxYouTrackVersion": "2024.2.0",
  "changeNotes": "Version 0.0.1: Feature 1",
  "vendor": {
    "name": "JetBrains",
    "url": "jetbrains.com",
    "email": "support@jetbrains.com"
  },
  "widgets": [
    {
      "key": "fields-first",
      "name": "Sample Widget",
      "description": "Optional description for the issue view widget",
      "extensionPoint": "ISSUE_FIELD_PANEL_FIRST",
      "indexPath": "index.html",
      "iconPath": "icon.png",
      "settingsSchemaPath": "sample-widget-settings.json",
      "permissions": ["READ_USER"],
      "defaultDimensions": {
        "height": "40px",
        "width": "80%"
      },
      "expectedDimensions": {
        "height": "200",
        "width": "1000"
      }
    }
  ]
}

Manifest Schema

The schema used to validate the manifest for a YouTrack app is hosted in the SchemaStore. Its web address is included in the sample manifest provided on this page.

Editors that support JSON schemas will provide auto-completion and contextual help based on the schema, so be sure to load the schema in your development environment.

A manifest.json has the following fields:

Field

Type

Description

Required

$schema

String

The web address of the schema used to validate the manifest for a YouTrack app. This schema is hosted in the SchemaStore at https://json.schemastore.org/youtrack-app.json

Editors that support JSON schemas will provide auto-completion and contextual help based on the schema. This can speed up the process of creating and editing the manifest, so be sure to include this reference in your file.

name

String

The name of the app. This is used as a unique identifier in YouTrack. If you upload two apps with the same name to your YouTrack site, the existing version of the app with the same name is overwritten. It is also used as a unique id of the app in the JetBrains Marketplace.

This field can only contain lowercase alphanumeric characters, hyphens, underscores, and tildes.

✓

title

String

The title of the app. This is a user-friendly name that is shown in the JetBrains Marketplace and the YouTrack UI.

This field is optional. When empty, the name of the app is shown in its place.

 

description

String

The description of the app. You can see this description in the app details on the Apps administration page. This is also used as the description of the app in the JetBrains Marketplace.

 

version

String

The version number assigned to the app package in major.minor.bugfix format. The default value is 0.0.0.

 

url

String

The website for the app. For example, a GitHub page or landing page for your company or product.

This value is shown as the Plugin Site in the JetBrains Marketplace.

 

icon

String

The name of the file with the app icon. Store this file at the root level of the app package.

 

iconDark

String

The name of the file with the app icon for the dark theme. Store this file at the root level of the app package. If you don't include a separate icon for the dark theme, YouTrack will use the icon image for both dark and light themes.

 

minYouTrackVersion

String

The minimum YouTrack version with which the app is compatible. If you attempt to upload or install an app in a YouTrack installation that runs a version lower than the value specified in the manifest, the operation fails.

The JetBrains Marketplace uses this value to help users find apps that are compatible with their YouTrack Server installations.

This field is backward-compatible with the workflow-scripting-api from the dependencies field in older versions of the manifest schema.

 

maxYouTrackVersion

String

The maximum YouTrack version with which the app is compatible. If you attempt to upload or install an app in a YouTrack installation that runs a version higher than the value specified in the manifest, the operation fails.

 

changeNotes

String

A description of changes available in a specific version of the app. This information is only displayed in the JetBrains Marketplace.

Change notes can also be added and updated directly in the marketplace.

 

vendorVendor

An object that contains the description of the app vendor.

This information is only used for apps that have been uploaded to your YouTrack site directly. Apps that are installed from the JetBrains Marketplace take the name, URL, and email from the vendor profile in the marketplace.

 

widgets

Array<Widget>

An array of widget objects included in the app. Each widget represents a frontend extension.

 

Widgets

Each widget object represents a particular frontend extension. Each widget is a custom inline frame (iFrame) object you embed into the native YouTrack UI.

A widget has the following fields:

Field

Type

Description

Required

key

String

The unique identifier of the widget.

This is a mandatory field that must be unique within the app.

This field can only contain lowercase alphanumeric characters, hyphens, underscores, periods, and tildes.

✓

name

String

The user-friendly name of the widget shown in the app settings in YouTrack. Widget names must be unique within one app.

 

description

String

The description of the widget.

Required for widgets embedded in the HELPDESK_CHANNEL extension point.

Optional for other extension points.

 

extensionPoint

String

The location in the YouTrack UI where the widget will be embedded.

For the full list of available extension points, see Extension Points.

✓

indexPath

String

The path to the index.html file that defines the content and structure of the widget. The path is relative to the widgets folder inside the app package.

Store the source code in an HTML file named index.html. Place this file directly in the widgets folder or in a dedicated subfolder.

✓

iconPath

String

The relative path to the file with the icon for the widget inside the app package.

  • Required for widgets embedded in the HELPDESK_CHANNEL extension point.

  • Optional for widgets embedded in the ARTICLE_OPTIONS_MENU_ITEM and ISSUE_OPTIONS_MENU_ITEM extension points.

 

settingsSchemaPath

String

The path to the JSON file that stores the settings scheme for Markdown widgets. It should be the path to a file somewhere inside the folder that stores the code for this particular widget.

 

permissions

Array<String>

The set of permissions required to view and use the widget. Depending on the app scope, these permissions can be required at the global or project level.

For widget extension points with project scopes, project-category permissions are checked on a per-project basis. For example, if you require the project-category LINK_ISSUE permission to view a widget that uses the project-scoped ISSUE_BELOW_SUMMARY extension point, users will only see this widget when working with projects where they have been granted the LINK_ISSUE permission.

To refer to a permission, use its unique identifier.

 

expectedDimensions

Object

The expected dimensions of the widget in pixels. YouTrack will try to display the widget according to these dimensions if the monitor settings allow.

Supported attributes are width (integer) and height (integer).

This field is supported by all extension points except MARKDOWN and DASHBOARD_WIDGET. If a value is provided for a widget that uses either of these two extension points, it is rejected by YouTrack.

 

defaultDimensions

Object

The default width and height of the widget.

Supported attributes are width (integer) and height (integer).

This field is only supported by widgets that use the MARKDOWN and DASHBOARD_WIDGET extension points. If a value is provided for a widget that uses any other extension point, it is rejected by YouTrack.

  • For a MARKDOWN widget, you can specify the dimensions in pixels or as a percentage. For example, "width": "100px" or "height": "40%".

  • Dimensions for a DASHBOARD_WIDGET are specified in fractional units. A fraction is equivalent to one cell in the dashboard grid. For example, "width": "8fr")

 

Vendor

This object stores basic information about the vendor of the app.

A vendor object has the following fields:

Field

Type

Description

Required

name

String

The name of the vendor.

✓

url

String

The URL of the vendor website.