Apps FAQ

Build a workflow when your solution only needs backend automation, such as changing fields, creating issues on a schedule, validating updates, or sending requests to an external service.

Build an app when you also need a custom user interface, a packaged set of modules, app-specific settings, dedicated storage, custom HTTP endpoints, or a solution that can be installed and managed as one unit.

You can also include workflow rules in an app package. For details, see Apps Versus Workflows.

An app can add widgets to supported locations in the YouTrack UI, expose custom HTTP handlers, declare app settings, store custom values in extension properties, and include JavaScript-based modules such as workflow rules.

For an overview of an app package, see App Package Overview. For the full list of widget locations, see Extension Points for Widgets.

An app can add content only to supported extension points. It cannot rewrite arbitrary parts of the YouTrack UI or change the behavior of built-in controls directly.

If you need to show custom controls on an issue, article, dashboard, project settings page, or another supported location, use a widget. If you need to react to changes in YouTrack data, use a workflow rule or HTTP handler.

Yes. Use a DASHBOARD_WIDGET for a widget that appears on a dashboard, or use MAIN_MENU_ITEM or ADMINISTRATION_MENU_ITEM for a full app page. The widget can read YouTrack data with the Host API or call app HTTP handlers that prepare data on the backend.

For available locations, see Extension Points for Widgets. For communication between widgets and YouTrack, see Host API.

Yes. A timer app usually combines an issue widget with custom HTTP handlers. The widget provides the start, stop, and save controls. The handlers read and update work items or store intermediate timer state.

For a complete example, see App Use Case: Simple Timer.

Yes, if the extension can be represented with widgets, YouTrack entities, app settings, and app-owned storage. For example, an app can show organization or customer context, store external identifiers, fetch data from a CRM, or add project-level configuration for the integration.

Use extension properties for app-owned values stored on YouTrack entities, and use app settings for values that administrators configure globally or per project.

Apps can store data in three common ways:

• Use YouTrack fields and entities when the data belongs to the regular project model.

• Use extension properties when the app owns the value and needs to attach it to an issue, article, project, user, or another supported entity.

• Use app global storage when the value belongs to the app rather than to a specific YouTrack entity.

For details, see Extension Properties.

No. App widgets run in a sandboxed IFrame and do not have access to localStorage, sessionStorage, web cookies, or other data stored in the local browser environment.

Use YouTrack data, extension properties, or app global storage instead. For details, see Local Storage.

Yes. Widget code can send HTTP requests, and backend modules can use workflow API modules to communicate with external services. For integrations that require server-side processing, credentials, or reusable endpoints, use custom HTTP handlers.

Store tokens, passwords, and API keys as secret app settings. For details, see Use Workflow API Modules in HTTP Handlers and Working with Settings for Secrets.

Use the Host API from widgets whenever possible. Requests sent through host.fetchYouTrack() use the current user's YouTrack session and do not require an authorization header in the widget code.

If you need to combine several requests, hide integration details, call an external service, or perform backend-only logic, call an app HTTP handler from the widget instead.

Yes, but the scheduled part is usually implemented as a workflow rule. Use an on-schedule rule to create or update issues at a configured interval. Package the workflow in an app if you also need a widget, app settings, or a reusable distribution package.

For workflow schedules, see On-schedule Rules.

When you request issues with the REST API, include the customFields attribute in the fields request parameter, then add a separate customFields request parameter for each field that you want to return.

For example, this widget request returns only the Score custom field for unresolved issues:

To request multiple custom fields, repeat the customFields parameter in the URL.

Use the standard YouTrack search range syntax for fields that store integer or float values. Ranges are inclusive, so use the lower bound that matches the first value you want to include.

For example, use this query to find issues where the Score field has a value greater than zero:

Use this query to find issues where the field has a value greater than or equal to zero:

Yes, from JavaScript modules that run in YouTrack. The @jetbrains/youtrack-scripting-api/search module accepts an object query with an extensionPropertiesQuery block.

Extension property queries match explicit property values. They are not a replacement for regular issue search fields when you need range queries, query completion, or sorting in the YouTrack issue list. Use a YouTrack custom field for values that users need to search or sort in the UI.

Widgets for ISSUE_OPTIONS_MENU_ITEM and ARTICLE_OPTIONS_MENU_ITEM open in a modal window. Set the expectedDimensions object in the widget manifest to request the modal size in pixels.

YouTrack tries to display the widget with these dimensions when the monitor settings allow. Dynamic resizing of an already opened modal is not currently exposed through the Host API.

No. Widgets opened from ISSUE_OPTIONS_MENU_ITEM and ARTICLE_OPTIONS_MENU_ITEM do not currently have a Host API method for closing their modal window programmatically.

Design the widget so users can complete the action and then close the modal using the standard YouTrack close control.

No. ATTACHMENT_OPTIONS_MENU_ITEM and COMMENT_OPTIONS_MENU_ITEM are not supported extension points for YouTrack apps.

Use a supported issue, article, or Markdown extension point instead. For the current list of supported extension points, see Extension Points for Widgets.

Full-page widgets such as MAIN_MENU_ITEM and ADMINISTRATION_MENU_ITEM are hosted in an iframe. Use the widget's own CSS to define the height of its root element and content.

The expectedDimensions manifest field accepts pixel dimensions and is treated as a display hint. It doesn't provide a dynamic 100% height mode for the available YouTrack page area.

Use global extension points for features that are available outside a single project, such as dashboard widgets, main menu pages, administration pages, user cards, and user profile settings. Use project-scoped extension points for features that should appear only in specific project contexts, such as issue widgets, article widgets, project settings tabs, and helpdesk channels.

For details, see Global and Project Scopes.

Define app settings in settings.json and use the appropriate scope for each setting. Project administrators can configure project-level settings in the projects where the app is attached. System administrators can configure global settings for the whole YouTrack service.

For details, see App Settings.

Use the permissions field in the widget manifest to require YouTrack permissions, and use widget guards to show a widget only when the current entity matches your conditions.

Permission restrictions are useful for access control. Guards are useful for context, for example showing an issue widget only for issues with a specific type or state.

For details, see App Permissions and Conditional Widgets.

No. JavaScript modules that run inside YouTrack do not need separate YouTrack credentials. Widget requests made through the Host API are authenticated as the current user.

If code outside the Host API calls the YouTrack REST API or Hub REST API, follow the authentication rules for these APIs. For details, see Authentication for Apps.

To upload an app to YouTrack and attach it to a project, a user must have the global Update Project permission.

Global HTTP handler modules require additional administrative permissions to manage. For details, see Scopes for HTTP Handlers.

Use the YouTrack app generator:

The generator creates the app package structure and can scaffold widgets and other app elements. For details, see App Quick Start Guide.

Use the experimental TypeScript-based toolchain when you want file-based routing, generated API types, and stronger type checking for widgets, handlers, app settings, and extension properties.

For details, see Enhanced DX for TypeScript Apps.

Build the app package, check that manifest.json is at the root of the package, confirm that widgets and JavaScript modules are stored in their expected locations, and upload the resulting ZIP file to a test YouTrack service.

For details, see Launch Checklist and Upload the App to YouTrack.

Start with the Simple Timer tutorial, the public YouTrack apps repository, and the YouTrack Demo App repository.

Yes. For local debugging, run the standalone React DevTools package on your workstation:

Then include the DevTools script in the widget HTML while debugging:

Remove this script before packaging or publishing the app.

No. Ring UI is recommended for visible controls and components that should match the YouTrack interface, but it doesn't replace a layout utility framework.

You can add your own CSS or a utility library for spacing and layout. Keep visible interactive components visually consistent with YouTrack by using Ring UI where practical.

Marketplace distribution is planned for apps. Until Marketplace installation is available, upload an app package to YouTrack manually.

For the current upload workflow, see Upload the App to YouTrack.