YouTrack Standalone 2021.2 Help

User Agreement

On the User Agreement page in YouTrack, you can store a user agreement that is presented to users who log in to YouTrack. This lets you collect and track individual acceptance of an information notice, such as a set of terms and conditions or privacy policy. Use this feature to inform users of your policy for handling the personal data that is stored in YouTrack as outlined in the General Data Protection Regulation (GDPR) requirements for businesses that operate in EU member states.

Format User Agreement Text

YouTrack lets you format your user agreement using Markdown.

The user agreement supports the standard Markdown implementation as described in the the CommonMark specification. Many of the extensions that are supported in issue fields are not available here. For details, see Markdown Syntax.

Enable a User Agreement

The purpose of this feature is to provide you with a means of collecting and tracking individual acceptance of your agreement or policy for handling personal information that is stored in YouTrack. When you enable the user agreement:

  • All users who log in to YouTrack are presented with the agreement. The agreement text is displayed as shown in the preview pane on the User Agreement page.

  • Users are presented with the option to accept or decline the agreement when they first log in after the agreement is enabled. If the agreement exceeds the amount of visible space in the dialog, the option to accept the agreement is not enabled until the user scrolls to the last line of the agreement.

  • Users who accept the agreement are granted access to YouTrack. The version number and date of acceptance are recorded in the profile of each user who accepts the agreement.

  • If a user declines the agreement, the user is logged out of YouTrack. To access the service, the user must log in again and accept the agreement.

To enable a user agreement:

  1. From the Administration menu, select Server Settings > SSL Keys.

  2. Enter or paste your agreement text in the input field.

    User agreement
    • You can format your agreement text using Markdown syntax.

    • The preview pane on the right displays the text as it will be shown in the agreement dialog.

    • Note that the agreement dialog only displays the agreement text and the buttons to Accept or Deny the agreement.

  3. When you are ready to publish the agreement, click the Save button.

    • The user agreement is saved as a new minor version.

  4. If you want to track acceptance for user accounts who access YouTrack using the REST API, enable the Require for REST API access option. For more information, see REST API Access and External Integrations.

  5. Click the Enable agreement button.

    User agreement enabled
    • The user agreement is enabled.

    • All users who log in to your YouTrack installation are presented with the agreement.

      User agreement dialog

    • Users must accept the agreement to access the service.

    • The date of acceptance and version number of the current agreement are stored in the user profiles of users who accept the agreement.

Update the User Agreement

If you have minor updates to the user agreement that do not materially affect your practices with regard to the personal information that you have previously collected from users, you can edit the agreement text and publish a new minor version. Users who have accepted the previous minor version are not asked to accept the new version. Only users who have not accepted the previously published version of the agreement are presented with the updated version of the agreement.

To publish a new minor version of the agreement:

  1. From the Administration menu, select Server Settings > User Agreement.

  2. Edit your agreement text in the input field.

  3. Click the Save button.

    • Your user agreement is saved as a new minor version.

    • The date of acceptance and version number of the updated agreement are stored in the user profiles of users who accept the agreement.

If you change your strategy for handling personal information to include activities that were not disclosed in a previous version, you can update the agreement text and invalidate the current version. All users, including users who accepted the previous version of the agreement, are asked to accept the updated agreement to use the YouTrack service.

To publish a new major version and invalidate the previous agreement:

  1. From the Administration menu, select Server Settings > User Agreement.

  2. Edit your agreement text in the input field.

  3. Select the Invalidate current agreement option.

  4. Click the Save button.

  5. Confirm the action in the Invalidate Current Agreement dialog.

    User agreement invalidate
    • Your user agreement is saved as a new major version.

    • The previous version of the agreement is invalidated.

    • All users are asked to accept the updated agreement on their next attempt to log in to YouTrack.

    • The date of acceptance and version number of the updated agreement are stored in the user profiles of users who accept the agreement.

Tracking Changes to the User Agreement

To prove that you are working within the guidelines for data processing in case of an incident, you need to track each version of the user agreement and its date of publication. While YouTrack provides the interface for presenting an agreement and tracking its acceptance on a per-user basis, it is not intended for use as a version tracking tool. Instead, YouTrack gives you the option to download the agreement text. This lets you record the publication of this information together with agreements that you track for other sites in a central repository.

The following options are available from the Download menu in the header:

OptionDescription
.txtDownloads the current version of the agreement as a text file. The file contains the agreement text as formatted in Markdown syntax as it is shown in the input field on the User Agreement page.
.htmlDownloads the current version of the agreement in raw HTML.

You can also track all of the changes that have been applied to your user agreement in YouTrack.

To track changes to your user agreement:

  1. From the Administration menu, select Server Settings > User Agreement.

  2. Click the Changes applied to User Agreement link in the header.

    • YouTrack opens the Audit Events page.

    • The page is filtered to show only events that are related to the user agreement.

  3. To browse changes to the agreement, select an event from the list and view the changes in the Details sidebar. The sidebar displays the Author, Timestamp, and a set of Changes that were applied to the agreement.

    User agreement audit events

  4. To export the complete set of changes that have been applied to the agreement, select all of the audit events and click the Download as .json button.

    • An events.json file downloads to your local directory.

    • This file contains a complete list of all of the changes that have been applied to the user agreement in JSON format.

Tracking User Acceptance

Another means of proving that you work within the guidelines for data processing is the ability to track user acceptance of the agreement. In YouTrack, this information is displayed in the Hub account for each user.

The YouTrack profile displays the latest version of The following information is recorded in YouTrack:

  • If the user has not yet accepted an agreement, the User agreement shows that acceptance of the current version is pending.

    User agreement acceptance user profile

  • If a user has accepted the current version of the agreement, the User agreement displays the accepted version number and the date and time when the user accepted the agreement.

    User agreement pending acceptance

  • If the user accepted a version of the agreement that has been invalidated, the User agreement shows the version number and date and time of the previously accepted version. The field also shows that acceptance of the current version is pending.

REST API Access and External Integrations

This User Agreement feature includes an option to require acceptance of the agreement to access YouTrack using the REST API. When enabled, user accounts that are created for integration or automation purposes can be blocked when the agreement is enabled or updated. This can result in unexpected login failures for external applications that are integrated with YouTrack.

  • If you enable the Require for REST API access option, you need to log every integration user into YouTrack through the user interface after the user agreement is enabled. You must also do the same every time the current version of the agreement is invalidated and replaced with a new major version.

  • If you wish to avoid this annoyance, disable the Require for REST API access option.

Last modified: 26 April 2021