Developer Portal for YouTrack and Hub Help

Global and Project Scopes

When building an app for YouTrack, it's important to understand the distinction between global and project scopes. These scopes determine the level at which features, settings, and extensions are available within the system.

Scopes for Extension Points

Each extension point for an app is designed to work at the global scope or project scope.

  • An extension point with a global scope is available throughout the system. This means it can be accessed by users outside the context of a specific project.

  • An extension point with a project scope is limited to a particular project. Widgets that use these extension points are only available in the context of a project where the app has been attached and the widget is active. Users will only have access to the widget if they have access to the project as well.

The following extension points have a global scope:

  • ADMINISTRATION_MENU_ITEM

  • DASHBOARD_WIDGET

  • MAIN_MENU_ITEM

  • MARKDOWN

  • USER_CARD

  • USER_PROFILE_SETTINGS

These extension points have a project scope:

  • ARTICLE_OPTIONS_MENU_ITEM

  • ISSUE_ABOVE_ACTIVITY_STREAM

  • ISSUE_BELOW_SUMMARY

  • ISSUE_FIELD_PANEL_LAST

  • ISSUE_FIELD_PANEL_FIRST

  • ISSUE_OPTIONS_MENU_ITEM

  • PROJECT_SETTINGS

  • HELPDESK_CHANNEL

For more information about extension points, see Extension Points.

Scopes for HTTP Handlers

The same concept applies to HTTP handlers, which are also accessible either at the global or project level.

HTTP handlers with the following endpoints are scoped at the global level:

  • global
  • user

HTTP handlers with the following endpoints are scoped at the project level:

  • issue
  • article
  • project

With HTTP handlers, you cannot mix global-level and project-level endpoints in a single handler. Any app that contains HTTP handlers that define endpoints for multiple scopes will be rejected by YouTrack. If you want to define custom endpoints for multiple scopes in a single app, use separate HTTP handlers for each scope.

  • When you attach an app that contains global-level HTTP handlers to a project, it doesn't change the scope for the endpoint. These global endpoints are still available at the system level even if they appear to be switched off using the visibility settings for the app itself.

  • Project-level handlers, on the other hand, must be activated per-project and are only accessible in the projects where the app has been attached and the module that contains the HTTP handler is active.

HTTP handler scopes also affect who has permission to manage modules for the app.

  • Modules that contain HTTP handlers for global-level endpoints can only be managed by users with the Low-level Admin Write permission. This permission is usually reserved for system administrators.

    If a user who doesn't have Low-level Admin Write permission installs or imports an app that contains a global module, the app will be deactivated automatically. It can only be activated by a user who has sufficient permissions.

  • Modules that only contain HTTP handlers for project-level endpoints can be managed by users with Update Project permission.

    Users with Update Project permission are not allowed to replace the endpoint for a project-scoped HTTP handler with an endpoint that requires a global scope.

For more information about HTTP handlers for YouTrack apps, see HTTP Handlers.

Last modified: 7 October 2024