Ontrack V4

Ontrack evolves, together with the CI/CD landscape, and it was time for a new major version, bringing changes which make it more versatile and flexible to deal with the amount of data that your pipelines create hour after hour, minute after minute.

Ontrack V4 is now the official version and it brings many changes, in many areas.

Security upgrades

OpenID Connect support

Ontrack, in parallel of built-in authentication and LDAP, now supports authentication based on Open ID Connect. In particular, this brings support for Okta & Keycloak authentication.

Several authentication sources can be mixed together, allowing for a smooth transition.

Support for the mapping of Okta & Keycloak groups to Ontrack groups is supported.

See the Ontrack documentation for more information.

Authentication tokens

Additionally to the new Open ID Connect integration, Ontrack can associate API tokens to any type of user, removing the need for passwords when interacting with the Ontrack API.

Those tokens can be used in-place of the former password or be used directly in a HTTP header.

Authentication is now required

The anonymous support for Ontrack is no longer supported and authentication is always required.

Major features

Support for pull requests

Whenever a Git pull request is associated with an Ontrack branch through its name, Ontrack will recognize it as a pull request and link it to the source and target branches when available in the system.

This makes pull requests first class citizens of the Ontrack knowledge base.

Build dependencies graphs

Ontrack is able to track links (dependencies) between builds. Ontrack V4 can use this information in order to display static and dynamic graphs about the state of dependencies between your different components.

At build level, this view statically represents the actual links between your different builds.

But Ontrack can go further and compute the expected links between your different branches based on past information, decorating the graph of dependencies as it grows.

Extensions can contribute to the graph by adding additional information.

Integration changes

Ontrack has been mostly interacted with using its REST API and a dedicated solution like a Jenkins plug-in.

With V4, additional ways  are possible, opening further integration with Ontrack from GitHub actions or any other CI platform.

The Ontrack CLI

Foremost among the way to interact with Ontrack comes the Ontrack CLI.

This is a lightweight multi-platform CLI, written in Go, interacting with the Ontrack new GraphQL schema.

Once downloaded, you can just configure it to target your Ontrack installation and run commands to setup your branch and build, to create validations and promotions, etc.

See the CLI documentation for instructions and examples.

GitHub action integration

For teams using GitHub actions, the nemerosa/ontrack-github-actions-cli-setup GitHub action allows an  integration of the Ontrack CLI into your workflows, including an easy setup of your projects, branches and builds.

For example:

- name: Setup the CLI
  uses: nemerosa/ontrack-github-actions-cli-setup@v1
    github-token: ${{ github.token }}
    only-for: nemerosa
    url: <ontrack-url>
    token: ${{ secrets.ONTRACK_TOKEN }}
    config: github.com
    indexation: 120

The nemerosa/ontrack-github-actions-cli-validation is also available to allow the creation of validation runs for your workflow steps, based on the information provided by the GitHub workflow.

The Jenkins plugin

The https://plugins.jenkins.io/ontrack/ Ontrack plugin for Jenkins has now a version 4, which is compatible with V3 & V4 (just a flag in the settings).

Note that the Jenkins plug-in might be deprecated at one point and replaced by a downloadable Jenkins pipeline library leveraging the Ontrack CLI. Stay tuned.

Enriched GraphQL schema

Finally, all those changes have been made possible by a humongous upheaval of the Ontrack GraphQL schema.

While the Ontrack V3 GraphQL schema was only about queries, V4 brings mutations and many additional queries.

Some queries have been deprecated in favor of pagination, in order to allow for the amount of data that Ontrack is now able to manage, but old APIs are still there. They will be removed in a future V5 version.

In order to explore the Ontrack GraphQL schema, you can go to the GraphiQL menu on the home page of your installation.

Minor changes

Settings page

The settings page has been refactored in order to allow for the number of additional settings brought by V4. Each section is now individually accessible from the left menu:

Global participant role

In V3, it was possible to grant a global read-only role to some users or groups of users, but the right to participate into a project had to be granted project per project, which was not really scalable.

In V4, you can now grant a global participation role to some users or groups of users, so that they can participate in all projects.

Stale branches new policies

Stale branches policies, additionally to the activity since last build, now support include/exclude regular expressions to protect branches:

Accounts can be locked

Built-in accounts can now be locked, allowing administrators to easily create guest accounts.

Bonus: you can use guest / guest at https://ontrack.nemerosa.net to try out the new V4 features.

Infrastructure and deployment changes

Quick start

To quickly start Ontrack V4 on your workstation, you can run:

curl -fsSLO https://github.com/nemerosa/ontrack/blob/master/compose/docker-compose.yml
docker-compose up -d

This sets up:

  • a Postgres database
  • an ElasticSearch (single node)
  • Ontrack running on port 8080

Go to http://localhost:8080 and start using Ontrack.

The initial administrator credentials are admin / admin.

ElasticSearch by default

In V3, the usage of Elasticsearch as a search engine was optional. In V4, Elasticsearch is now a default requirement and must be provided for Ontrack to work properly.


The base JDK of Ontrack is now JDK 11. The base Docker image at nemerosa/ontrack:4 is based on the azul/zulu-openjdk:11.0.6 image.

Configuration as code

Ontrack V4 brings support for the "configuration as code" (CasC) of your Ontrack installation.

Security & other settings are already supported and new features will be available version after version.

For example, to setup Okta as a source of authentication:

      - id: okta
        name: My Okta
        description: The Okta account used by my company
        issueId: https://<okta domain>.okta.com/oauth2/default
        clientId: <Client ID of the application in Okta>
        clientSecret: <Client secret of the application in Okta>
        groupFilter: ontrack-.*

CasC files can be linked to your installation and reloaded dynamically using management end points or regular API calls.

See the Ontrack CasC documentation for more information.


Some features have been dropped out of V4.

Dropping support for Subversion

Subversion proved too difficult to maintain in the context of V4 and has been removed. By refocusing on Git (and GitHub, GitLab, Bitbucket, etc.), the code has become simpler to maintain.

Removal of branch templates

Branch templates have been removed. The correct way to manage branches in Ontrack is to define them as code from your different CI integration platforms, using native plugins or the Ontrack CLI.


The official documentation of Ontrack is available at https://static.nemerosa.net/ontrack/release/latest/docs/doc/index.html.

Since V4, many sections are still under heavy refactoring and are currently missing. They'll appear as soon as they are finished. Please reach out to the support if you need more information.


  • V2 version of Ontrack becomes unmaintained, even for bug fixes
  • V3 (3.43 branch) of Ontrack becomes LTS with only support for bug fixes
  • V4 becomes the activily developed version

Note that paying support is available - please contact ontrack@nemerosa.com for more information.

Support can be provided through GitHub issues or in Gitter.

SaaS availability

Finally, Ontrack V4 has made possible the creation of a SaaS offering, so that you can quickly get started with your own Ontrack instance, without any need for installation or setup.

To get your own https://<instance>.ontrack.run instance, please contact the sales at ontrack@nemerosa.com