Skip to main content

Drift Detection

Drift Detection automatically monitors your HubSpot portal for manual changes that deviate from your Git-based "source of truth." This helps you maintain control over your metadata configuration and catch unauthorized or accidental modifications.

What is Drift?​

Drift occurs when someone makes changes directly in HubSpot that differ from the metadata stored in your Git repository. For example:

  • A team member creates a new workflow directly in HubSpot instead of deploying it from Git
  • Someone modifies a property definition in the HubSpot UI
  • A pipeline stage is renamed or deleted manually
  • Form fields are changed without going through your change management process

Drift detection helps you identify these discrepancies so you can:

  • Maintain consistency across environments
  • Enforce change management policies
  • Audit unauthorized changes
  • Prevent configuration conflicts during deployments

How Drift Detection Works​

1. Baseline Configuration​

You configure drift detection by specifying:

  • Baseline Repository: The Git repository containing your "source of truth" metadata
  • Baseline Branch: The Git branch to compare against (e.g., main, prod)
  • Ignored Types: Metadata types to skip during drift analysis (optional)
  • Ignored URNs: Specific metadata items to exclude from drift checks (optional)

2. Automatic Monitoring​

Once enabled, drift detection runs automatically during each scheduled metadata backup:

  1. Extract Current State: HubSpot Deploy fetches the latest metadata from your portal
  2. Compare Against Baseline: The system compares the current state with the specified Git branch
  3. Identify Changes: Any differences are flagged as potential drift
  4. Filter Results: Changes matching ignored types or URNs are excluded
  5. Record Report: If drift is detected, a drift report is created with a full changeset

3. Notifications​

When drift is detected, you receive:

  • Email notification with the number of changes detected
  • Drift report in the Instance dashboard showing all differences
  • Link to comparison view where you can review the exact changes

Setting Up Drift Detection​

Prerequisites​

Before enabling drift detection, you need:

  • ✅ A HubSpot connection configured
  • ✅ A Git repository connected with baseline metadata
  • ✅ At least one successful backup to establish the baseline

Configuration Steps​

  1. Navigate to Instance Dashboard

    • Go to Connections → Select your HubSpot portal
    • Click the Drift Detection tab

  2. Enable Drift Detection

    • Toggle the Status switch to enable monitoring

  3. Configure Baseline

    • Baseline Repository: Select the Git repository containing your source of truth
    • Baseline Branch: Specify the branch to compare against (default: main)

  4. Set Exclusions (Optional)

    • Ignored Metadata Types: Check any types you want to skip (e.g., if you allow manual list management)
    • Ignored URNs: Add specific item identifiers to exclude from drift checks

  5. Save Configuration

    • Click Save Configuration to apply your settings

  6. Test the Setup

    • Click Run Check Now to trigger an immediate drift check
    • The task will run in the background and results will appear in the Drift History section

Understanding Drift Reports​

Drift History​

The Drift History section shows all detected drift events:

ColumnDescription
DetectedWhen the drift was identified
Changes CountNumber of differences found
ActionsLink to view the full comparison

Viewing Drift Details​

Click View Diffs on any drift report to see:

  • Side-by-side comparison of Git baseline vs. current HubSpot state
  • Change type for each item (added, modified, deleted)
  • Detailed diff showing exactly what changed
  • Metadata type and internal name for each affected item

Common Drift Scenarios​

Scenario 1: Unauthorized Workflow Changes​

What happened: A team member modified a workflow directly in HubSpot.

Drift Detection Result:

  • Status: modified
  • Type: workflows
  • Changes: Workflow steps, enrollment criteria, or actions were altered

Resolution:

  1. Review the changes in the drift report
  2. If the changes are valid, update your Git repository to match
  3. If unauthorized, revert by deploying the baseline version from Git

Scenario 2: New Properties Created Manually​

What happened: Someone created custom properties in HubSpot UI instead of deploying from Git.

Drift Detection Result:

  • Status: added
  • Type: standard_objects or custom_objects
  • Changes: New properties appear in HubSpot but not in Git

Resolution:

  1. Decide if the properties should be kept
  2. If yes, extract them to Git using a backup
  3. If no, delete them from HubSpot to restore consistency

Scenario 3: Pipeline Stages Renamed​

What happened: Deal or ticket pipeline stages were renamed in HubSpot.

Drift Detection Result:

  • Status: modified
  • Type: pipelines
  • Changes: Stage labels or display order changed

Resolution:

  1. Review the changes
  2. Update Git baseline if the changes are intentional
  3. Redeploy from Git if the changes should be reverted

Best Practices​

1. Use a Dedicated Baseline Branch​

Create a dedicated branch (e.g., production-baseline) that reflects your production portal's intended state. This keeps your drift detection separate from active development branches.

2. Set Appropriate Exclusions​

Some metadata types may be managed manually by design:

  • Lists: If your team creates lists directly in HubSpot for campaigns
  • Email Templates: If marketing creates templates in the HubSpot editor
  • Forms: If forms are created ad-hoc for landing pages

Add these to Ignored Types to reduce noise in drift reports.

3. Review Drift Reports Regularly​

Make drift review part of your weekly or monthly operations:

  • Assign someone to review new drift reports
  • Document decisions about whether to keep or revert changes
  • Update your baseline Git branch to reflect approved changes

4. Combine with Scheduled Backups​

Drift detection runs automatically during scheduled backups. Set your backup frequency based on how quickly you need to detect drift:

  • Daily backups: Catch drift within 24 hours
  • Hourly backups: Near real-time drift detection for critical portals

5. Use Notifications​

Enable email notifications for drift detection so your team is alerted immediately when changes are detected. Configure notification preferences in your workspace settings.

Manual Drift Check​

You can trigger a drift check manually at any time:

  1. Go to Instance Dashboard → Drift Detection tab
  2. Click Run Check Now
  3. The drift check task will be queued and run in the background
  4. Results will appear in the Drift History section within a few minutes
tip

Manual drift checks are useful after:

  • Making changes directly in HubSpot for testing
  • Onboarding a new team member who may have made manual changes
  • Investigating suspected configuration issues

Troubleshooting​

No Drift Reports Appearing​

Possible causes:

  • Drift detection is not enabled
  • No baseline repository is configured
  • The baseline branch doesn't exist or has no metadata
  • All changes match ignored types or URNs

Solution: Verify your drift configuration and ensure at least one backup has run successfully.

Too Many False Positives​

Possible causes:

  • Baseline branch is outdated
  • Metadata types that should be ignored are not excluded
  • Specific items that change frequently are not in the ignored URNs list

Solution:

  1. Update your baseline branch to match the current intended state
  2. Add frequently-changing types to Ignored Types
  3. Add specific item URNs to Ignored URNs (format: type:internalName)

Drift Check Task Stuck​

Possible causes:

  • Background worker is not running
  • Large portal with many metadata items

Solution:

  • Wait 10-15 minutes for large portals
  • Check the Backups tab to see if the backup task is processing
  • If stuck for more than 30 minutes, contact support

Drift Detection vs. Comparisons​

FeatureDrift DetectionManual Comparison
PurposeAutomatic monitoring for unauthorized changesAd-hoc comparison between any two sources
TriggerRuns automatically during backupsCreated manually by user
BaselineFixed Git branch configured in settingsAny combination of portals, repos, branches
NotificationsSends alerts when drift is detectedNo automatic notifications
Use CaseContinuous compliance monitoringOne-time migration or investigation

Security & Permissions​

Who Can Configure Drift Detection?​

Only workspace admins can:

  • Enable or disable drift detection
  • Configure baseline repository and branch
  • Set ignored types and URNs

Who Can View Drift Reports?​

Both admins and members can:

  • View drift history
  • Open drift reports
  • Review comparison details

See Permissions for the complete permissions matrix.

FAQ​

Does drift detection affect backup performance?​

Drift detection adds 10-30 seconds to each backup run, depending on portal size. The backup itself completes first, then drift detection runs as a secondary step. If drift detection fails, the backup is not affected.

Can I disable drift detection temporarily?​

Yes. Toggle the Status switch to disable drift detection. You can re-enable it at any time without losing your configuration.

What happens to old drift reports?​

Drift reports are stored indefinitely. You can manually delete old reports from the Drift History section if needed.

Can I get drift notifications in Slack?​

Slack notifications are planned for a future release. Currently, drift alerts are sent via email only.

  • Backups - Scheduled metadata backups that trigger drift detection
  • Comparisons - Manual comparison tool for investigating differences
  • Deployments - Apply changes to restore consistency after drift is detected