Track changes using Jenkins

The change tracking feature allows you to designate changes you want to monitor to see how they affect your customers and systems.

While you can designate which changes you want to monitor by using GraphQL or our CLI, you can also record changes using pipelines in Jenkins.

A pipeline will call whatever build you specify and also pass additional environment variables to the build process. This populates the data that is needed for your deployment to show up in charts across New Relic. You'll see the results in the change tracking UIs, and you can use this information to understand the impact of changes on entity health.

Before you get started make sure you're using Jenkins version 2.222.4 or greater.

Manage the plugin

To record changes you want to track, you need a special plugin, which you can easily add or remove from your Jenkins instance.

Complete the following steps as a Jenkins administrator.

Add the plugin

To add the plugin:

1. Download the plugin from here, and if the filename is changed during download, rename the file to newrelic-deployment-notifier.hpi.

   Tip

   Note that this is a temporary download location for the plugin. We'll let you know when you can download this directly in Jenkins.

2. Open Jenkins, and click Manage Jenkins.

   

3. Click Manage Plugins.

   

4. Click Advanced.

   

5. Under Deploy Plugin, click Choose File and upload the file newrelic-deployment-notifier.hpi.

6. To finish the installation, make sure no jobs are running, and then restart Jenkins. You can also check the box Restart Jenkins when installation is complete and no jobs are running:

Remove the Plugin

To remove the plugin using Plugin Manager:

1. Click Installed.

   

2. Roll it back to the previous version by entering deploy in the search box, selecting New Relic Deployment Notifier Plugin, and then clicking the rollback symbol.

   

3. You can also uninstall it by clicking the X icon.

Create and run the pipeline

Follow these steps to create a pipeline script that will pass your deployment details to Jenkins when it runs your build. A Jenkins pipeline is a list of steps that are chained together. You can create a Jenkins pipeline in one of two ways:

• Create a Jenkinsfile and put it at the root of a source code repository
• Use the pipeline script functionality of Jenkins

Each stage consists of a list of steps, and one of the steps in this part (likely the very last one) is to call the NewRelicDeploymentNotifier to put a marker for a successful build.

The plugin we've created takes the GUID as a parameter. You can identify the GUID as a variable in the Environment section and use it as a variable in subsequent steps. The build is called by putting it in a stage and list of steps.

1. Go to the pipeline tab, and at the bottom, click Pipeline Syntax:

   

2. Click the Sample Step dropdown and select step: General Build Step.

   

3. Under Build Step, select New Relic Deployment Notifications.

   

4. Complete the following fields (we've included the REST API fields for people not using the GraphQL API):

   Field	GraphQL API	REST API	Description
   API Key	Required	Required	API Credentials to conduct the deployment action in New Relic. Credentials can be created by creating new credentials in Jenkins using a username and password. Specify any identifier for the username, and the API key for the password.
   applicationID	N/A	Required	This is only used for calls to the REST API. Do not include this if you're creating a call to the GraphQL endpoint.
   Description	Optional	Optional	Insert a description of what you are tracking.
   Revision	N/A	Required	Revision for the deployment.
   Changelog	Optional	Optional	Reference to the list of changes incurred in the deployment.
   Commit	Optional	N/A	A hash to reference the commit ID.
   Deeplink	Optional	N/A	A deep link to either the Jenkins job or any other reference to the deployment.
   EntityGuid	Required	N/A	The application entity in reference to the deployment (see More about the application GUID).
   DeploymentType	Optional	N/A	The type of deployment that is being conducted.
   GroupId	Optional	N/A	An identifier to reference a cluster of changes.
   Timestamp	Optional	N/A	Optional timestamp in Unix Epoch long format. If not provided, then we will set it to the time we received the request, which will be the number of milliseconds since the Unix Epoch.
   Version	Required	N/A	Required field for the version of what's being deployed.
   User	Optional	Optional	The user conducting the deployment. This is a free-form field. In Jenkins, we recommend you specify either the name on the commit or something like "Jenkins auto deploy."

5. Click Generate Pipeline Script.

6. Copy the script, return to the main pipeline page, and paste it into the pipeline script.

   

7. Execute the pipeline script to create your deployment marker in New Relic.

Move this pipeline script to GitHub

You can store pipeline scripts in GitHub. To retrieve the pipeline script, you can specify the location of the GitHub repository when creating an application in Jenkins.

More about the application GUID

Currently, GUIDs cannot be assigned dynamically to the pipeline. You must find the entity GUID in New Relic (see Learn about New Relic entities and then hardcode this value in the pipeline script to report deployment notifications for that entity. This information is not sensitive and can be stored publicly.

The credentials used to update the application should mitigate sending bad deployment markers. In addition, the credentials are referenced by ID in Jenkins, so they do not need to be stored in source code repositories.

How to detect if failures occur

Pipeline syntax errors will halt the pipeline. Pipeline parsing errors (like missing build steps) will halt the pipeline. You should troubleshoot these using Jenkins tools to construct appropriate pipeline scripts. Using the WYSIWYG Pipeline Syntax tool in Jenkins can help you appropriately construct the New Relic deployment notification.

If the plugin detects an error, it should not halt the pipeline. It will log an exception and a stack trace, and then it will continue. This helps you prevent interruptions when building and deploying applications.

What's next

After you've designated the changes you want to track, you can analyze the effect of those changes in the New Relic UI. For details, see How to view and analyze your changes in New Relic.