Using an External Code Editor

You can use the web-based workflow editor to make a quick edit or write a simple rule. But if you’re used to working in a full-featured development environment, you can actually write your workflows in any IDE that supports JavaScript.

To let you work where you're most comfortable, we've put together and published packages to the npm registry service that you can install in your development environment. This functionality is not specific to any single platform. You should be able to configure any environment that supports JavaScript to write and manage workflow scripts for YouTrack.

Workflow API Package

The youtrack-scripting-api package contains the complete YouTrack workflow API. When you plug this package into your code editor, your code-completion tools suggest valid functions, methods, and properties for all of the entities that are available in the API.

YouTrack App Tools

The youtrack-apps-tools package contains utilities that help you manage YouTrack app packages when you work in an external code editor. This lets you write and update apps and workflows for YouTrack in JavaScript in your preferred development environment.

The package includes scripts that let you synchronize local changes with your YouTrack installation. The following commands are available:

Command	Description
list	This command lists all of the app packages that are available in your YouTrack installation. To use this command, specify the following parameters: `host` — Your YouTrack base URL. For YouTrack Cloud instances hosted on `myjetbrains.com`, your base URL includes the trailing `/youtrack`. For example: `https://company.myjetbrains.com/youtrack` `token` — A permanent token that grants access to the YouTrack service. You can generate your own permanent tokens to authenticate with YouTrack on the Authentication tab of your Hub account. For more information, see Manage Permanent Tokens. This command uses the following syntax: youtrack-app list --host --token
download	This command downloads the referenced app package from your YouTrack installation. If you don't specify a directory with the output parameter, a directory with the name <appName> is created in the current working directory. The app package files are extracted into the new directory. Otherwise, the app package is downloaded into the directory that is specified in the output parameter. This command uses the following syntax: youtrack-app download <appName> --host --token [--output, --overwrite]
upload	This command uploads the app package from the specified directory to your YouTrack installation. First, the script checks the reference directory for a `manifest.json` file that contains the name of the app. For compatibility with older workflow packages, the script also accepts a `package.json` file. If neither file is present or the file does not specify the app name, the name of the directory is used as the name of the uploaded app. This command uses the following syntax: youtrack-app upload <dir> --host --token

Command

Description

list

This command lists all of the app packages that are available in your YouTrack installation. To use this command, specify the following parameters:

host — Your YouTrack base URL.
For YouTrack Cloud instances hosted on myjetbrains.com, your base URL includes the trailing /youtrack. For example: https://company.myjetbrains.com/youtrack
token — A permanent token that grants access to the YouTrack service.
You can generate your own permanent tokens to authenticate with YouTrack on the Authentication tab of your Hub account. For more information, see Manage Permanent Tokens.
This command uses the following syntax:
youtrack-app list --host --token

download

This command downloads the referenced app package from your YouTrack installation.

If you don't specify a directory with the output parameter, a directory with the name <appName> is created in the current working directory. The app package files are extracted into the new directory. Otherwise, the app package is downloaded into the directory that is specified in the output parameter.

This command uses the following syntax:

youtrack-app download <appName> --host --token [--output, --overwrite]

upload

This command uploads the app package from the specified directory to your YouTrack installation. First, the script checks the reference directory for a manifest.json file that contains the name of the app. For compatibility with older workflow packages, the script also accepts a package.json file. If neither file is present or the file does not specify the app name, the name of the directory is used as the name of the uploaded app.

This command uses the following syntax:

youtrack-app upload <dir> --host --token

Package Installation

To work with these packages in your IDE, you need to install and run Node.js. This also installs the npm package manager that lets you work with the scripting package in your projects.

Next, install the workflow API package and app tools in your development environment. The easiest way to get started is to install the package globally with the following commands:

npm install -g @jetbrains/youtrack-scripting-api
npm install -g @jetbrains/youtrack-apps-tools

If you prefer to install packages as dependencies in your development environment, enter:

npm install --save-dev @jetbrains/youtrack-scripting-api
npm install --save-dev @jetbrains/youtrack-apps-tools

As long as your installation doesn't use a certificate that is issued by your own certificate authority (CA) or is self-signed, you can establish a connection using a personal permanent token. You can generate your own permanent tokens on the Authentication tab of your Hub account. For instructions, see Create a Permanent Token.

If you are using a certificate that is not issued by a known CA, you need to use specific variables in your Node.js environment to enable a connection between your IDE and the YouTrack installation. For instructions, see Special Instructions for SSL Certificates.

If you have just a few custom workflows and don't need to update them very frequently, you might get by with basic commands. For regular updates, the need to specify a host and token with each request is a bit unwieldy. Follow the instructions in the next section to simplify this process and use these commands with fluidity.

Working with Environment Variables

You can streamline app tool commands by storing your connection details in environment variables instead of passing them to every command.

The youtrack-app command reads the following environment variables:

YOUTRACK_HOST - the base URL of your YouTrack installation. For YouTrack Cloud instances hosted on myjetbrains.com, include the trailing /youtrack.
YOUTRACK_API_TOKEN - a permanent token that grants access to the YouTrack service.

You can generate your own permanent tokens on the Authentication tab of your Hub account. For instructions, see Create a Permanent Token.

Store these values in your shell profile, IDE run configuration, or secret manager. If you also pass --host or --token to a command, the command-line values take precedence over the environment variables.

The last step is to write scripts that run the supported commands. The quickest way is to create a package.json file and add your scripts to the scripts field.

This package.json file is an npm project file that stores command scripts and development dependencies. The descriptor file for the app or workflow package is manifest.json.

To create the file and build your script:

In your CLI, enter the command npm init. This starts a utility that helps you build the JSON file.
For each field in the file, specify a new value or accept the suggested default. Once you have specified values for all of the fields, the JSON is displayed in the CLI.
Confirm the creation of the file by accepting the prompt Is this ok? (yes).
- The package.json file is added to the current project.
Open the package.json file and edit the scripts field. You can also remove irrelevant fields from the file. Use the following example as a guide.
{ "name": "myyoutrackworkflows", "version": "1.0.0", "description": "Custom workflows for my YouTrack installation", "scripts": { "list-prod": "youtrack-app list", "download-prod": "youtrack-app download", "upload-prod": "youtrack-app upload" }, "author": "Me", "devDependencies": { "@jetbrains/youtrack-apps-tools": "0.0.XX", "@jetbrains/youtrack-scripting-api": "20XX.X.XXXXX" } }
Set the values for the @jetbrains/youtrack-apps-tools and @jetbrains/youtrack-scripting-api parameters to match the current versions of these packages.

At this point, you can run the commands without specifying the values for your host and token. Use the following commands to run your scripts:

npm run list-prod
npm run download-prod -- <app name>
npm run upload-prod -- <directory>

The basic process is as follows:

Use the download command to copy an app package from your installation to your development environment.
Make your changes.
Use the upload command to update the app package in YouTrack.

Keep in mind that you're still pushing updates straight to your production environment. If you'd like to work in a more controlled manner, follow the instructions in the next section.

Connecting to a Test Environment

One of the major advantages of using an external editor to write workflows is that you can connect to multiple YouTrack installations. As with any code development project, you should first upload and test your changes in a sandbox environment. Only when you’re sure it’s working as intended should you deploy the code in production.

We recommend that you create your own sandbox environment. Our free plan is a great solution for testing workflows.

If your production environment is a YouTrack Server installation, you can download and install a local copy and use the free plan. You can update your local installation to the same version as your production environment to ensure your workflows behave as expected.
If you use YouTrack Cloud, you can register for a separate instance that uses the free plan. Our hosted servers are upgraded to the latest version of YouTrack automatically.

Once you have set up an account in a test environment, you can use the test environment values when you run your app tool commands.

To adapt your script to connect to a test environment:

Generate a permanent token in your test environment.
Set YOUTRACK_HOST to the base URL of your test environment.
Set YOUTRACK_API_TOKEN to the permanent token from your test environment.
Run the same scripts that you use for production. The app tools use the host and token from the current environment.

Your typical process would look something like this:

Download an app package from your production environment with the command:
npm run download-prod -- <app name>
Update the workflow in your IDE.
Switch YOUTRACK_HOST and YOUTRACK_API_TOKEN to the values for your test environment.
Upload the modified package to your test environment with the command:
npm run upload-prod -- <directory>
Test the workflow in your YouTrack sandbox environment.
Repeat steps 2 through 5 until your workflow behaves as expected.
Switch YOUTRACK_HOST and YOUTRACK_API_TOKEN back to the values for your production environment.
Upload the final version of your package to your production environment with the command:
npm run upload-prod -- <directory>

If you are the only person who is responsible for the customization of your YouTrack installation, you might stop here. With this setup, you can safely update your workflows while working exclusively in your favorite development environment.

If there are other developers in your organization who write scripts for their own projects, you might want to get everyone to work together. Follow the instructions in the next section and share this setup with your team.

Working as a Team

One of the biggest advantages of the setup in this section is that it supports collaboration. With a few modifications, you can build a platform that other developers can use to manage workflows in your YouTrack installation. As this setup is not specific to any single environment, these developers can be working with any IDE that supports JavaScript in any operating system.

The first thing you can do is commit a shared npm package.json file. Each developer who works with this setup needs to generate and store their own personal token, but the scripts can be shared by everyone.

Use the following example as a guide.

{
    "name": "ouryoutrackworkflows",
    "version": "1.0.0",
    "description": "Custom workflows for our YouTrack installation",
    "scripts": {
        "list": "youtrack-app list",
        "download": "youtrack-app download",
        "upload": "youtrack-app upload",
        "validate": "youtrack-app validate"
    },
    "author": "Me",
    "devDependencies": {
        "@jetbrains/youtrack-apps-tools": "0.0.XX",
        "@jetbrains/youtrack-scripting-api": "20XX.X.XXXXX"
    }
}

The scripts read the host and token from YOUTRACK_HOST and YOUTRACK_API_TOKEN. This lets each developer choose the target YouTrack installation in their local environment without changing the shared project files.

The last step is to upload your project to a repository. When you upload your project to a repository, other users can follow these steps and start coding:

Connect to the repository and download a local copy of the project. Be sure to include the npm package.json file in your project files.
Generate personal permanent tokens for the YouTrack installations that they use and save them as environment variables.

Now each developer should be able to perform the following actions:

Download project files from the repository.
Update workflow scripts in their local environment.
Upload and test their updates in the sandbox until they behave as expected.
Upload the revised scripts to the production environment.
Push their changes back to the repository, updating the version of the revised script.

For a real-life example, check out our YouTrack Custom Workflow Repository. Here, we upload workflows that support a range of use cases that are not covered by the default workflows in YouTrack. Everyone is welcome to download scripts from the repository and adapt them to suit specific business cases. If you have a script that you’d like to share with the community, submit a pull request!

Special Instructions for SSL Certificates

If your YouTrack domain uses an SSL certificate that is issued by a known certificate authority, you can establish a connection using just your personal permanent token. Your certificate is already included in CA certificate store that is built into Node.js. For certificates that are issued by a CA that is not recognized automatically or is self-signed, you need to modify the environment variables in Node.js to recognize or ignore your certificate.

Private Certificate Authorities

If your certificate is issued by a CA that is not recognized automatically, you need to add your certificate to the list of certificates that are recognized by Node.js.

To add your certificate, use the environment variable NODE_EXTRA_CA_CERTS=file in your scripts. This variable is supported in Node.js versions v7.3.0 (or LTS versions 6.10.0 and 4.8.0) and later.

To work with a private certificate:

Open your YouTrack installation in a web browser.
Use your browser tools to export the certificate. Specific instructions vary for different browsers.
Store the certificate file in a directory that is accessible from your development environment.
Set NODE_EXTRA_CA_CERTS to the full path to the certificate file in the same environment where you store YOUTRACK_HOST and YOUTRACK_API_TOKEN.
Run your youtrack-app scripts as usual. Node.js reads the extra certificate from the environment variable.

Self-signed Certificates

If you work in a closed environment and use a self-signed certificate, you can disable the secure connection over TLS with the environment variable NODE_TLS_REJECT_UNAUTHORIZED=0.

Set this variable in the same environment where you store the host and token for your local installation. Then run the youtrack-app commands as usual.

Even though this type of workaround is often done in a development environment, it is not secure. If you are not aware of the potential pitfalls, avoid this practice. Never use this variable to connect to your production environment.

13 May 2026