Nemerosa

Setting up Ontrack with Jenkins

Damien Coraboeuf -

Ontrack collects data about everything which happens in your CI/CD ecosystem.

Such collection of data starts usually with your CI engine. Ontrack itself is agnostic when it comes to the CI engine but this article will focus on getting you started, step by step, with Jenkins.

In a future article, we'll see how to adapt your Jenkins pipelines so that information is sent to Ontrack.

This very article focuses on the technical aspects of configuring both Ontrack & Jenkins so they can talk to each other.

Installation of Ontrack

The Ontrack quick start allows to have an installation of Ontrack using the following Docker Compose command:

curl -fsSLO https://github.com/nemerosa/ontrack/blob/master/compose/docker-compose.yml
docker compose up -d
Other installation methods are available. See the documentation for more information.

Using the quick start, Ontrack will be available at http://localhost:8080 and the default credentials are admin / admin.

Generate an API token for the admin user:

curl -fsSL --user admin:admin http://localhost:8080/rest/tokens/new
# Copy the returned token - you'll need it to configure Jenkins

Installation of Jenkins

If you don't have a Jenkins installation, you can start it locally using instructions in the official Jenkins documentation.

Since Ontrack runs on port 8080, make sure Jenkins runs on another port.

No specific plugin is needed for Jenkins to work with Ontrack.

Jenkins configuration

While you can use the Ontrack CLI to send information from your Jenkinsfileto Ontrack, it's more efficient to use the Ontrack Jenkins pipeline library, a collection of pipeline steps which interact with Ontrack.

While Jenkins Configuration as Code should be the preferred way to install this library in your Jenkins instance, you can just this as well using the Jenkins UI.

In your Jenkins instance, go to Manage Jenkins > Configure Jenkins.

Navigate to the Global Pipeline Libraries section and add a new library with the following information:

  • name: ontrack-jenkins-cli-pipeline
  • check Modern SCM
  • check GitHub
  • GitHub credentials must be filled
  • GitHub repository HTTPS URL:‌‌ https://github.com/nemerosa/ontrack-jenkins-cli-pipeline

Still in the Configure Jenkins page, add the global environment variable ONTRACK_URL and set it to your Ontrack installation.

This global URL is a convenient way to avoid configuring the calls to Ontrack in each and every pipeline.

Save the settings.

Now, go to Manage Jenkins > Manage Credentials and register a ONTRACK_TOKEN entry:

  • click on the (global) domain
  • click on Add Credentials
  • select Secret Text as the Kind of credentials
  • put the API token you generate before as the Secret
  • enter ONTRACK_TOKEN as the ID of these credentials
  • enter any description you like, for example "API token used to connect to Ontrack"
  • click OK to save this credentials entry

The Ontrack Jenkins CLI library is now registered and ready to be used.

For users already configuring their Jenkins as code, you can use the following code:

jenkins:
  globalNodeProperties:
    - envVars:
        env:
          - key: ONTRACK_URL
            value: <Ontrack URL>
credentials:
  system:
    domainCredentials:
    - credentials:
      - string:
          description: "Ontrack authentication token"
          id: "ONTRACK_TOKEN"
          scope: GLOBAL
          secret: "<Ontrack token>"
globallibraries:
    libraries:
      - name: ontrack-jenkins-cli-pipeline
        allowVersionOverride: true
        defaultVersion: ""
        implicit: false
        includeInChangesets: true
        retriever:
          modernSCM:
            scm:
              git:
                remote: "git@github.com:nemerosa/ontrack-jenkins-cli-pipeline.git"
                credentialsId: <the ID of your GitHub credentials>

Ontrack configuration for Jenkins

In Ontrack, go to your user menu and:

  • select Jenkins configurations
  • click on Create a configuration
  • set a meaningful Name
  • set URL to the base URL of your Jenkins instance
  • set a Username and a Password to connect from Ontrack to your Jenkins instance. Only read access is needed.

Conclusion

That's it.

Jenkins is now ready to run pipelines that can send information to Ontrack, and Ontrack can keep references to the Jenkins jobs having sent this information in the first place.

What's next?

Stay tuned with the next article which will cover the basics of integrating your Jenkins pipelines with Ontrack.