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.

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 to third-party services. For server-side integration logic, credentials, logic shared by several widgets, or calls that should run in YouTrack's backend sandbox, use custom HTTP handlers.

HTTP handlers can use modules from the YouTrack workflow API package @jetbrains/youtrack-scripting-api, including the http module, to communicate with external services. Widgets can call these handlers with host.fetchApp().

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.

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.

Currently, there are no dedicated extension points for attachments or comments.

If you need to add an action to the Show more menu for a comment or attachment, use a workflow action rule instead. Starting from YouTrack 2024.2, action rules can be applied to issue comments, article comments, issue attachments, and article attachments.

You can also 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, and administration pages. Use entity- or project-scoped extension points for features that belong to a specific context, such as issues, articles, projects, users, or 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.

Installing and updating apps from JetBrains Marketplace require the Low-level Admin Write permission. Uploading a custom app package to YouTrack requires either the global Update Project permission or the system Low-level Admin Write permission.

For development and testing, the upload command generated by the YouTrack app generator can use a permanent token for an account with Update Project permission. To attach project-level app modules to projects, a user needs Update Project permission for the corresponding projects.

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.

App widgets run in a sandboxed iframe, so YouTrack's frontend styles don't apply to widget content directly.

Use Ring UI components for visible controls when practical, and add widget-specific CSS for layout and spacing. This helps custom widgets look consistent with the surrounding YouTrack user interface while keeping their styles isolated.

Yes. YouTrack administrators can install apps directly from JetBrains Marketplace when the YouTrack site has internet access. In YouTrack, open Administration > Apps, click Add app..., and select Browse JetBrains Marketplace.

Installing an app from Marketplace preserves the link between the app and Marketplace, so updates can be installed from YouTrack when a new version is published. Installing and updating Marketplace apps requires the Low-level Admin Write permission. You can still upload a ZIP file manually for custom apps that aren't distributed through Marketplace if you have the required upload permissions.

For details, see JetBrains Marketplace in the YouTrack documentation.