Track changes with GitHub Actions

You can use New Relic's change tracking feature with GitHub Actions to monitor the impact of changes on your customers and systems. GitHub Actions integration allows you to automatically track changes during your release pipeline and view the results in New Relic.

New Relic's GitHub Action supports two approaches:

Change tracking events (Recommended): The modern approach that provides flexibility to track any type of change, including deployments, feature flags, configuration changes, and business events
Change tracking deployments (Legacy): The traditional deployment-focused approach for tracking application deployments

Prerequisites

GitHub repository with Actions enabled
New Relic personal API key
Entity GUID or entity search query for your application

GitHub secrets setup

Configure these GitHub secrets in your repository:

NEW_RELIC_API_KEY: Your New Relic personal API key
NEW_RELIC_DEPLOYMENT_ENTITY_GUID: New Relic Entity GUID to create markers on

Sugerencia

For multiple applications, use descriptive secret names like NEW_RELIC_DEPLOYMENT_ENTITY_GUID_App123, NEW_RELIC_DEPLOYMENT_ENTITY_GUID_App456, etc.

Choose your tracking method

The change tracking events provide a comprehensive change tracking with flexible categorization, custom attributes, and entity search capabilities. Use this method for any type of change including deployments, feature flags, business events, and operational changes.

Key	Description
`apiKey`	Your New Relic personal API key
`commandType`	Must be set to `"changeTrackingCreateEvent"` to use the events API

Key	Description
`category`	The category of the change event. For supported categories, refer to change tracking categories
`type`	The type of the change event. For supported types, refer to change tracking types
`entitySearch`	Specify the entity to associate with the change tracking event via query
`version`	When category is `Deployment`, the version of the deployment. This is required if `category` is selected as `"Deployment"`
`featureFlagId`	When category is `Feature Flag`, the ID of the feature flag. This is required if `category` is `"Feature Flag"`
`description`	High-level description visible in the Overview page and Change Details page
`shortDescription`	Brief description for quick identification in markers and activity streams
`user`	Username to associate with the change event
`groupId`	Group ID to link related change events
`customAttributes`	Key-value pairs of custom attributes in JavaScript object format
`changelog`	When category is `Deployment`, summary of changes visible in Change Details page
`commit`	When category is `Deployment`, commit SHA visible in Change Details page
`deeplink`	When category is `Deployment`, deep link to deployment source
`timestamp`	Start time as milliseconds since Unix epoch. Defaults to current time
`validationFlags`	Validation flags (e.g., `[ALLOW_CUSTOM_CATEGORY_OR_TYPE]`)
`region`	New Relic account region

Examples

jobs:
newrelic:
  runs-on: ubuntu-latest
  name: New Relic ChangeTracking Event 
  steps:
    # This step builds a var with the release tag value to use later
    - name: Set Release Version from Tag
      run: echo "RELEASE_VERSION=${{ github.ref_name }}" >> $GITHUB_ENV
    - name: Test change event deployment marker
      uses: newrelic/deployment-marker-action@v2.6.0
      with:
        apiKey: ${{ secrets.NEW_RELIC_API_KEY }}
        commandType: "changeTrackingCreateEvent"
        entitySearch: "id='${{ secrets.NEW_RELIC_DEPLOYMENT_ENTITY_GUID }}'"
        version: "${{ env.RELEASE_VERSION }}"
        category: 'Deployment'
        type: 'Basic'
        changelog: "https://github.com/${{ github.repository }}/blob/master/CHANGELOG.md"
        commit: "${{ github.sha }}"
        deepLink: "https://example.com/deployment"
        description: "Automated Release via Github Actions"
        user: "${{ github.actor }}"
        groupId: "deploy-group-1"
        timestamp: "${{ github.event.release.published_at }}"
        customAttributes: '{cloud_vendor: "vendor_name", region: "us-east-1", isProd: true, instances: 2}'

Legacy method specifically designed for deployment tracking. Use this method if you need compatibility with existing deployment-focused workflows.

Sugerencia

New Relic recommends migrating to change tracking events using changeTrackingCreateEvent for better flexibility and feature support. Deployment markers will continue to work but have limited functionality compared to change events.

Optional inputs for deployments

Key	Description
`changelog`	Summary of changes visible in the Deployments page
`commit`	Commit SHA visible in the Deployments page
`description`	High-level description visible in Overview and Deployments pages
`deeplink`	Deep link to the deployment source
`deploymentType`	Deployment type: `BASIC`, `BLUE_GREEN`, `CANARY`, `OTHER`, `ROLLING`, or `SHADOW`
`groupId`	Group ID to link related deployments
`user`	Username to associate with the deployment
`region`	New Relic account region

Examples

name: Change Tracking Marker
on:
  release:
    types: [published]

jobs:
  newrelic:
    runs-on: ubuntu-latest
    name: New Relic
    steps:
      # This step builds a var with the release tag value to use later
      - name: Set Release Version from Tag
        run: echo "RELEASE_VERSION=${{ github.ref_name }}" >> $GITHUB_ENV
      # This step creates a new Change Tracking Marker
      - name: New Relic Application Deployment Marker
        uses: newrelic/deployment-marker-action@v2.6.0
        with:
          apiKey: ${{ secrets.NEW_RELIC_API_KEY }}
          region: "US"
          guid: ${{ secrets.NEW_RELIC_DEPLOYMENT_ENTITY_GUID }}
          version: "${{ env.RELEASE_VERSION }}"
          user: "${{ github.actor }}"

What's next

View and analyze changes

Learn advanced techniques for correlating change data with performance metrics and system behavior.

Query your changes

Learn how to query your change data in New Relic.

Notify your team

Learn how to set up notifications for your change tracking events.

Prerequisites

GitHub secrets setup

Sugerencia

Choose your tracking method

Required attributes

Optional attributes

Examples

Action for event tracking

Sugerencia

Required attributes

Optional attributes

Optional inputs for deployments

Examples

Example workflows for deployments

What's next

View and analyze changes

Query your changes

Notify your team

Key	Description
`apiKey`	Your New Relic personal API key
`guid`	The entity GUID to apply the deployment marker
`version`	Metadata to apply to the deployment marker. For example, latest release tag

Track changes with GitHub Actions

Prerequisites .css-21sua1{background:none;border:none;width:0;padding:0;}

GitHub secrets setup

Sugerencia

Choose your tracking method

Optional attributes

Examples

Action for event tracking

Sugerencia

Required attributes

Optional attributes

Examples

Example workflows for deployments

What's next

View and analyze changes

Query your changes

Notify your team

Prerequisites