---
title: Track changes with GitHub Actions
source: https://docs.newrelic.com/docs/change-tracking/config/github-actions
---

You can use New Relic's change tracking feature with [GitHub Actions](https://docs.github.com/en/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 [#prerequisites]

-   GitHub repository with Actions enabled
-   New Relic [personal API key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/)
-   Entity GUID or entity search query for your application

### GitHub secrets setup [#secrets]

Configure these [GitHub secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#about-encrypted-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

> #### 💡 TIP
>
> 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 [#tracking-methods]

### Change tracking events

The [change tracking events](https://github.com/marketplace/actions/new-relic-application-deployment-marker#changetrackingcreateevent-recommended) 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.

**Required attributes**

| Key           | Description                                                                                          |
| ------------- | ---------------------------------------------------------------------------------------------------- |
| `apiKey`      | Your New Relic [personal API key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys) |
| `commandType` | Must be set to `"changeTrackingCreateEvent"` to use the events API                                   |

**Optional attributes**

| Key                | Description                                                                                                                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category`         | The category of the change event. For supported categories, refer to [change tracking categories](https://docs.newrelic.com/docs/change-tracking/config/nerdgraph/#standard-types) |
| `type`             | The type of the change event. For supported types, refer to [change tracking types](https://docs.newrelic.com/docs/change-tracking/config/nerdgraph/#standard-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

**Action for event tracking**

```yaml
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}'
```

### Change tracking deployments (Legacy)

**Legacy method** specifically designed for [deployment tracking](https://github.com/marketplace/actions/new-relic-application-deployment-marker#changetrackingcreateevent-recommended). Use this method if you need compatibility with existing deployment-focused workflows.

> #### 💡 TIP
>
> 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.

**Required attributes**

| Key       | Description                                                                                          |
| --------- | ---------------------------------------------------------------------------------------------------- |
| `apiKey`  | Your New Relic [personal API key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys) |
| `guid`    | The entity GUID to apply the deployment marker                                                       |
| `version` | Metadata to apply to the deployment marker. For example, latest release tag                          |

**Optional attributes**

##### Optional inputs for deployments [#deployment-optional]

| 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 [#deployment-examples]

**Example workflows for deployments**

```yaml
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 [#whats-next]

[View and analyze changes](https://docs.newrelic.com/docs/change-tracking/view-analyze-data/)

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

[Query your changes](https://docs.newrelic.com/docs/change-tracking/query-data)

Learn how to query your change data in New Relic.

[Notify your team](https://docs.newrelic.com/docs/change-tracking/change-tracking-webhooks)

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