App Manifest

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.
`vendor`	Vendor	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.

Last modified: 7 November 2024