Marketplace Submission Checklist

Pre-submission Checklist

Use this summary before each Marketplace submission. You can also add these checks to your release checklist.

How the Review Works

The YouTrack team reviews the listing and code, installs the app, and tests its behavior. Each submission goes through the following checks:

Ten Common Reasons Apps Are Sent Back

These issues come up often in reviews. Checking them first can save you another round of reviews.

1. Tokens stored in cleartext. Declare them in settings.json with "format": "secret". Don't put them in extension properties. For details, see Secrets and Credentials.

2. global or user endpoints without access checks. Declare permissions or check access explicitly in code. For details, see HTTP Handlers and Access Control.

3. Access rules enforced only in the UI. Hiding a button doesn't stop someone from calling the endpoint directly. For details, see HTTP Handlers and Access Control.

4. Trusting IDs from the request body. Accepting an entity ID from a request without checking the caller's access can expose data they aren't allowed to see. For details, see HTTP Handlers and Access Control.

5. Synchronous outbound HTTP (postSync, getSync, and so on), especially calls to AI services, including large language model (LLM) APIs. Use the *Async methods instead. For details, see Outbound HTTP Calls (Async Required).

6. Obfuscated code. The review team needs readable code to verify what the app does. For details, see Package and Manifest.

7. Undisclosed calls to third-party servers, such as license servers, analytics, CDNs, or hosted editors. For details, see Marketplace Listing.

8. Links that ignore the YouTrack context path. These break when YouTrack Server is hosted at /youtrack. For details, see Frontend (Widget) Code.

9. Widgets that are unreadable in dark theme. Check every widget with YouTrack's dark theme turned on. For details, see UI and User Experience.

10. Error responses that leak stack traces or internal details. Return a short message and log the details on the server. For details, see HTTP Handlers and Access Control.

Marketplace Listing

The listing is the first thing administrators see. The review team also starts with the listing.

• Write a clear description. Explain what the app does, who it is for, and its main features.

• Include at least one screenshot. Show the app in action inside YouTrack. Screenshots should show the key features, not just a logo or a settings form.

• Add a Getting Started section if setup goes beyond installation. Explain any extra steps: configuration, permissions, attaching the app to projects, and setting up external accounts or tokens. Make sure the instructions match the current app version, including file names, menu names, and setting labels.

• Add change notes for each version (recommended). Describe what actually changed. Make sure the submitted code includes the fixes you mention.

• Include a vendor name. For details, see vendor in the manifest.

• Set the correct compatibility range. If backend scripts make outbound HTTP calls or use async functions, set minYouTrackVersion in manifest.json to "2026.2" or later. This version requirement doesn't apply to requests that widgets make from the browser. For details, see the manifest schema and Outbound HTTP Calls (Async Required).

• Disclose third-party data processing. If the app sends any data outside YouTrack, say so in the listing and link to a privacy policy. This applies to license checks, telemetry, user counts, hosted editors, AI services, and CDNs. Say what is sent, to whom, and why.

Package and Manifest

For the basic package layout, see Launch Checklist.

• Backend scripts are at the package root. YouTrack registers HTTP handlers and workflow rules from .js files in the app's root folder. If they sit in a subfolder such as backend/, the handlers are never registered, and only the widgets work. For details, see App Package Overview.

• File paths in manifest.json match the files in the ZIP package. Check indexPath, iconPath, and settingsSchemaPath. A wrong path can cause a broken icon or a missing settings dialog. For details, see widgets in the manifest.

• settings.json is a valid schema for YouTrack. If you include "$schema", use http://json-schema.org/draft-07/schema#: the https:// form fails validation when the settings are saved. Open the settings in YouTrack and save them once to confirm. Remove leftover boilerplate, such as a demo $id or a placeholder title. For details, see App Settings.

• Permission restrictions match the intended users. The permissions property doesn't grant permissions to the app. It limits who can see a widget or call an endpoint. An empty list means no restriction. Make sure each restriction matches the permissions needed for the action. For details, see App Permissions.

• The app declares no unused extension properties. Remove properties the app declares but doesn't use. For details, see Extension Properties.

• Backend scripts and widget bundles contain no obfuscated code. Standard bundler minification is fine. Output from tools like javascript-obfuscator (string arrays, self-defending wrappers, disabled console) is not.

• License checks use readable code. If you need license enforcement, sign license data on your server and verify the signature in readable code.

• Remove development leftovers and use production service URLs. Remove debug endpoints and panels, verbose logging of server responses, and internal documentation. Replace any staging, sandbox, or development URLs for license, payment, or API services with production URLs.

Secrets and Credentials

Check secret handling carefully before submission. These issues can block approval and may require several review cycles to resolve.

• The package contains no hardcoded credentials. This includes API keys, bearer tokens, custom authentication headers, and YouTrack permanent tokens. Hardcoded credentials count as a Blocker issue, even if they're obfuscated or used only for a trial.

• Tokens, passwords, and client secrets use "format": "secret" in settings.json.

  { "type": "object", "properties": { "apiToken": { "type": "string", "format": "secret", "title": "API token" } } }

  Secret values are masked (<***>) in the administration interface, in REST responses, and in console.log() output. A setting declared only as "type": "string" leaves its value readable in cleartext by administrators and through the REST API. Secret fields also work in arrays of objects. For details, see Working with Settings for Secrets.

• Secrets are never stored in extension properties. Extension properties (AppGlobalStorage, User, Project, Issue) have no secret type. Their values are stored in cleartext. This covers OAuth access and refresh tokens, webhook secrets, and tokens copied from app settings. For details, see Extension Properties.

• Custom encryption isn't a substitute for secret storage. If you use XOR or another reversible scheme and ship the key in the package, anyone with the ZIP can recover the secret. Use "format": "secret" in settings.json.

• No endpoint returns a secret. This also applies to responses sent to the app's own widgets. If a widget needs an operation that uses a secret, run it in a backend handler and return only the result.

• Keep service account permissions and token scopes to the minimum needed. If the app creates a service account or asks for a token, request only the services and permissions it needs. For example, don't grant access to the Hub (user management) service if the app only calls the YouTrack API.

• The app reuses only accounts it created. Before reusing an existing service account, check that the app created it. One way is to store the account's ID when the app creates it and check that ID before reuse. Otherwise, the app may issue a token for an account controlled by someone else.

• Leaked secrets are revoked or rotated. If a secret ever shipped in a package or was exposed through an endpoint, revoke or rotate it. Removing it from the next version isn't enough because old packages are still available.

HTTP Handlers and Access Control

YouTrack enforces visibility differently depending on endpoint scope. Make sure you understand which protections YouTrack provides automatically and which you need to add. For details, see Scopes for HTTP Handlers and the HTTP handler reference.

All endpoints are subject to app activation, handler visibility, and any declared permissions checks.

Before submitting your app, test endpoint access with an account that has minimal permissions. The YouTrack team performs these checks during review.

Outbound HTTP Calls (Async Required)

Marketplace apps must use async HTTP for all outbound calls from backend scripts. The backend *Async methods are available from YouTrack 2026.2, so if your backend calls external services, set minYouTrackVersion to "2026.2" or later. This doesn't apply to requests that widgets make from the browser.

For details about Asynchronous Functions, see supported script types, execution limits, sharing state, and HTTP calls and chaining. For the HTTP methods, see Send Requests after Transaction Completion.

Synchronous calls keep the current transaction or request thread open while waiting for a response. The synchronous methods are doSync, getSync, postSync, putSync, patchSync, deleteSync, and headSync. Use the corresponding *Async methods. For HEAD requests, use doAsync('HEAD', ...).

• In onChange and action rules, they keep the write transaction open and can block other users who are updating the same entities.

• In onSchedule rules, they count toward the default 3-minute execution limit (see Workflow Rules and Performance).

• In HTTP handlers, they hold a request thread.

Async functions are supported in onChange, action, and onSchedule rules, HTTP handlers, and custom MCP tools.

If more than one condition in the following table applies, use the highest severity.

Workflow Rules and Performance

Your app runs inside the customer's YouTrack. Slow rules can make YouTrack less responsive for other users.

Storing Data

Use extension properties for small amounts of app data. Keep values small, avoid frequent writes, and plan for concurrent updates. For details, see App Global Storage.

• No secrets in extension properties. For details, see Secrets and Credentials.

• Avoid frequent writes. Each write updates the YouTrack database. Writing a property for every matching issue in a frequently scheduled onSchedule rule can put extra load on YouTrack.

• Keep values small. Don't store logs, large JSON blobs, or whole datasets. Cap the size of anything users can submit.

• Plan for concurrent edits. Concurrent updates to the same extension property can overwrite each other. If two users save the same JSON blob, the last write wins. Store data per entity rather than in one global blob, or add a revision check.

• Keep user data private. Keep each user's settings separate, and return only the settings the caller is allowed to see. Don't keep every user's settings in one shared global blob that every handler reads and returns.

• Use settings for configuration. For administrator-configured values, settings.json (global or project scope) gives you validation, a UI, and secret masking. For details, see App Settings.

Frontend (Widget) Code

Widgets run in sandboxed iframes. The review covers every bundle, including minified ones.

• External requests are essential to the app and disclosed in the listing. This includes CDN stylesheets and scripts. Bundle Ring UI and other libraries instead of loading them from unpkg or similar at runtime.

• Widgets don't evaluate strings as code or dynamically import remote code. Don't use eval, new Function, or dynamic import() of remote code.

• The app doesn't generate undisclosed background traffic. Don't use sendBeacon, WebSocket connections to external hosts, tracking pixels, or document.cookie unless they are essential and disclosed.

• The app doesn't use long encoded strings to hide URLs, code, or credentials. Check long base64-encoded, hexadecimal, and similarly encoded strings.

• postMessage targets a specific origin, not '*', when it carries data such as OAuth codes.

• User content is sanitized before it reaches innerHTML or dangerouslySetInnerHTML. This includes Markdown rendered with HTML enabled and document previews. Block javascript: links.

• The widget doesn't cache sensitive data in localStorage. Issue summaries and descriptions cached in the browser can remain accessible after the user loses access to those issues.

• Links respect the context path. Self-hosted YouTrack can run under a path such as https://host/youtrack. Root-absolute links starting with /, such as /issue/ABC-1, skip that context path. Relative links can also point to the wrong place because the widget's base URL is the app's resource folder. Fetch the context path and build your links from it:

  const host = await YTApp.register(); const { contextPath } = await host.fetchYouTrack('config?fields=contextPath'); // contextPath is the configured path prefix, such as "/youtrack", or "" at the root URL. const issueUrl = `${contextPath}/issue/${issueId}`;

  Set target="_top" on these links so they open in the YouTrack page, outside the widget iframe. For example: <a href={issueUrl} target="_top">. For details, see the YTApp object and the fetchYouTrack method.

• Widget requests use the scope and entity ID required by the endpoint. For example, an issue-menu widget must not use an issue ID where a project ID is expected. A widget can call a global endpoint regardless of the widget's scope. For details, see HTTP endpoint scopes.

• Every REST call a widget makes works for the users who see it. Some endpoints and fields return 403 for regular users, for example /api/groups?fields=users. You can't tell from the path alone: some /api/admin/... endpoints work for regular users. Test each endpoint and field set with an account that has only the permissions your widget's intended users need. If an operation needs more access, put it in a backend handler that checks whether the caller is allowed to perform it.

UI and User Experience

Apps should feel like part of YouTrack.

• Use Ring UI or match YouTrack's look and feel. Use Ring UI (@jetbrains/ring-ui) for buttons, inputs, loading indicators, alerts, and dialogs. If you don't use it, match YouTrack's colors, spacing, and fonts. For details, see Ring UI.

• Widgets work with the dark theme enabled. Switch YouTrack to the dark theme (click your avatar, then select Appearance > Dark) and check every widget: text, backgrounds, dialogs, and disabled states. Follow YouTrack's theme, not the operating system's prefers-color-scheme setting.

• Widgets fit their intended size. Check that content isn't clipped, no inner scrollbars appear at the default size, and there are no large empty areas. When specifying dimensions in the manifest, use defaultDimensions for dashboard and Markdown widgets and expectedDimensions for other supported extension points. For details, see widget size and widget properties in the manifest.

• Widgets use the system font stack. Avoid decorative fonts.

• Write the product name as "YouTrack" throughout the listing, UI text, setting labels, dialogs, and error messages. Don't use Youtrack, youtrack, or YOUTRACK.

• Give empty values meaningful labels. Don't display [object Object], undefined, or ?. Use YouTrack's wording, such as "Unassigned" or "No value," where appropriate.

• Show widgets only to users with the required permissions. If a menu item would lead to an access error, hide it with widget permissions or a guard. For details, see App Permissions and Conditional Widgets.

• The interface is localized consistently. Don't mix languages in your interface text, and make sure every translation key exists for every language your app supports.

• Field values and labels created by the app contain no spelling mistakes. These values become part of customers' data.

Functional Quality

The review covers every feature described in your listing. Check the following before submission:

• Every advertised feature works on a clean YouTrack Server. Test outside your development environment.

• Project-scoped widgets work after the app is attached to a project. Issue, article, project-settings, and helpdesk widgets appear only in projects the app is attached to. Test this and explain the attachment step in Getting Started. For details, see Extension Points for Widgets.

• The app works for regular users. Test with an account that has only the permissions the app's intended users need.

• Built-in groups work in permission checks. Check membership with user.isInGroup(groupName) rather than searching user.groups, which may not include built-in groups such as "All Users" or "Registered Users". For details, see User.isInGroup.

• The app handles edge cases. Test empty or optional fields, missing work item types, special characters in user input and queries (&, #, +), and URLs with query strings.

• Multi-step operations don't lose or duplicate data. If an operation has several steps, such as copying and then deleting an item, order the steps or roll them back so a failure halfway through doesn't cause data loss or duplication.

• The app makes configuration changes only with the administrator's consent. Opening an administration page must not create fields, change colors, or edit bundles. Ask the administrator to confirm these changes before applying them.

• Updates keep existing data and settings. Check that the updated app can still read and use data and settings from the previous version.