Skip to main content

Comparison Management

Comparisons allow you to view metadata differences between two sources (HubSpot portals or GitHub repositories). This guide covers creating, viewing, renaming, and deleting comparisons.

Overview​

A metadata comparison analyzes the differences between two environments:

  • Source: Where metadata is read from (origin)
  • Target: Where changes would be deployed to (destination)

Both source and target can be either:

  • HubSpot Portal (via OAuth or Private App connection)
  • GitHub Repository (specific branch)

Creating a Comparison​

Prerequisites​

You need at least 2 sources configured before creating a comparison:

  • Minimum: 2 HubSpot portals, OR 2 GitHub repos, OR 1 portal + 1 repo
  • Sources must be different (cannot compare a portal to itself)

From the Comparisons Screen​

  1. Navigate to Comparisons in the main navigation
  2. Click New Comparison button (top-right)
  3. In the modal:
    • (Optional) Enter a descriptive name (e.g., "Production vs Staging")
    • Select Source (origin) from the dropdown
    • Select Target (destination) from the dropdown
  4. Click Initialize Comparison

The system will:

  1. Create the comparison record with pending status
  2. Queue extraction tasks for both source and target
  3. Redirect you to the comparison view
  4. Begin populating metadata from both environments
  5. Calculate differences once both sides are populated

From Quick Actions​

You can also create comparisons from:

  • Connections screen: Click "Compare" on any portal
  • GitHub screen: Click "Compare" on any repository

Comparison Lifecycle​

Status Flow​

pending → in_progress → completed
StatusDescription
pendingComparison created, waiting to start
in_progressExtracting metadata from source and/or target
completedBoth sides populated, differences calculated

Population Process​

Each comparison tracks two population flags:

  • source_populated: Source metadata extraction complete
  • target_populated: Target metadata extraction complete

The comparison view shows real-time progress for each side with:

  • Metadata type being processed
  • Number of items extracted
  • Completion percentage

Viewing Comparisons​

Comparisons List​

The Comparisons screen shows all your comparisons with:

  • Name: Custom name or auto-generated ID
  • Source: Origin environment (portal or repo)
  • Target: Destination environment (portal or repo)
  • Actions: View or delete buttons

Mobile view: Card-based layout with all details
Desktop view: Table layout with sortable columns

Comparison Details​

Click View or the comparison name to open the diff viewer, which shows:

  1. Header:

    • Comparison name
    • Source and target labels
    • Status badge
    • Action buttons (Deploy, Refresh)

  2. Diff Table:

    • All metadata items with differences
    • Change types: create, update, delete, no_change
    • Metadata type grouping
    • Side-by-side comparison

  3. Changeset Panel (right sidebar):

    • Selected items for deployment
    • Dependency resolution
    • Deployment controls

  4. Deploy History (bottom panel):

    • Past deployments from this comparison
    • Status, timestamp, and logs

Renaming Comparisons​

Comparisons are auto-named by default (e.g., "Comparison a1b2c3d4"). You can rename them for clarity:

How to Rename​

  1. Navigate to Comparisons screen
  2. Hover over the comparison name
  3. Click the pencil icon that appears
  4. Enter the new name in the modal
  5. Click Save

Keyboard shortcut: Press Enter to save after typing

Naming Best Practices​

  • Use descriptive names that indicate the comparison purpose
  • Include environment names: "Production → Staging"
  • Add dates for time-based comparisons: "Pre-Migration Snapshot"
  • Use consistent naming conventions across your team

Examples:

  • ✅ "Prod vs Dev - Q1 2024"
  • ✅ "Staging → Production"
  • ✅ "Pre-Release Validation"
  • ❌ "Comparison 1"
  • ❌ "test"

Deleting Comparisons​

When to Delete​

Delete comparisons when:

  • They're no longer needed for reference
  • You want to clean up old test comparisons
  • The comparison was created by mistake
  • You need to free up storage space

How to Delete​

  1. Navigate to Comparisons screen
  2. Find the comparison to delete
  3. Click the trash icon (🗑️)
  4. Confirm deletion in the modal

⚠️ Warning: Deletion is permanent and cannot be undone. The comparison record, changeset, and associated metadata will be removed.

What Gets Deleted​

  • Comparison record
  • Calculated changeset
  • Population progress data
  • Associated metadata snapshots

What's Preserved​

  • Deployment history (stored separately)
  • Source and target connections
  • Original portal/repo data

Exporting Metadata to ZIP​

You can download all metadata from a comparison as a ZIP archive. This is useful for:

  • Offline review: Examine metadata without accessing the web interface
  • Backup: Keep a local copy of metadata at a specific point in time
  • Sharing: Send metadata to team members or support
  • Analysis: Process metadata with external tools

What's Included​

The ZIP archive contains:

  • All metadata items from the selected side (source or target)
  • Files organized by metadata type and hierarchy
  • YAML format for each item
  • Folder structure matching the metadata organization

File Structure​

metadata-export-12345678-1234567890.zip
├── custom_objects/
│   ├── project.yaml
│   └── invoice.yaml
├── custom_object_property/
│   ├── project/
│   │   ├── project_name.yaml
│   │   ├── project_status.yaml
│   │   └── project_owner.yaml
│   └── invoice/
│       ├── invoice_number.yaml
│       └── invoice_amount.yaml
├── workflows/
│   ├── lead_nurture.yaml
│   └── deal_followup.yaml
├── forms/
│   ├── contact_us.yaml
│   └── demo_request.yaml
└── ...

How to Export​

From Comparison View​

  1. Open the comparison you want to export
  2. Click the Export button (download icon) in the toolbar
  3. Choose which side to export:
    • Export Source: Download metadata from the source environment
    • Export Target: Download metadata from the target environment
  4. Your browser will download the ZIP file

From Instance Metadata View​

  1. Navigate to a HubSpot connection
  2. Click View Metadata button
  3. Click the Export button in the toolbar
  4. The ZIP file will download automatically

File Naming​

ZIP files are automatically named with:

  • Connection ID (first 8 characters)
  • Timestamp (Unix timestamp)
  • Format: metadata-export-{connectionId}-{timestamp}.zip

Example: metadata-export-a1b2c3d4-1704067200000.zip

Use Cases​

Offline Review​

Download metadata before a deployment to review changes offline:

  1. Create comparison between environments
  2. Export both source and target
  3. Extract ZIP files locally
  4. Use a diff tool to compare YAML files
  5. Review changes without internet connection

Backup Before Major Changes​

Create a snapshot before making significant changes:

  1. Export current portal metadata
  2. Store ZIP file with descriptive name
  3. Make changes in HubSpot
  4. If needed, reference the backup to restore settings

Sharing with Team​

Share metadata with team members who don't have system access:

  1. Export metadata from comparison
  2. Send ZIP file via email or file sharing
  3. Team members can review YAML files
  4. Discuss changes before deployment

External Analysis​

Process metadata with custom scripts or tools:

  1. Export metadata as ZIP
  2. Extract files to local directory
  3. Run analysis scripts on YAML files
  4. Generate reports or validate configurations

Working with Exported Files​

Reading YAML Files​

Each YAML file contains the complete metadata for one item:

# Example: contact_property.yaml
name: favorite_color
label: Favorite Color
type: enumeration
fieldType: select
groupName: contactinformation
options:
  - label: Red
    value: red
  - label: Blue
    value: blue
  - label: Green
    value: green

Comparing Exports​

To compare two exports:

  1. Export source and target from a comparison
  2. Extract both ZIP files to separate folders
  3. Use a diff tool (e.g., diff, Beyond Compare, WinMerge)
  4. Compare folders to see differences

Limitations​

  • Export size: Large portals (>5000 items) may take longer to download
  • Format: Only YAML format is supported (no JSON export)
  • Filtering: Exports include all metadata types (no selective export)
  • UI availability: Export button may not be visible in all views yet

Troubleshooting​

Export Button Not Visible​

Cause: Feature is being rolled out and may not be available in all views yet.

Solution:

  • Check if you're viewing a completed comparison
  • Ensure you have the latest version of the application
  • Contact support if the button is missing

Download Fails or Times Out​

Cause: Large portal with many metadata items.

Solution:

  • Wait a few moments and try again
  • Check your internet connection
  • Contact support if the portal is extremely large (>10,000 items)

ZIP File is Empty or Corrupted​

Cause: Export process was interrupted.

Solution:

  • Delete the partial download
  • Try exporting again
  • Ensure stable internet connection during download

Cannot Open YAML Files​

Cause: YAML files require a text editor.

Solution:

  • Use any text editor (VS Code, Sublime Text, Notepad++)
  • Do not use Microsoft Word or similar document editors
  • YAML files are plain text and human-readable

Permissions​

Comparison management requires specific workspace permissions:

ActionRequired Permission
View comparisonscomparisons:read
Create comparisonscomparisons:create
Rename comparisonscomparisons:update
Delete comparisonscomparisons:delete

Note: Workspace admins have all permissions by default.

Common Workflows​

Comparing Two Portals​

Use case: Compare production and staging HubSpot portals

  1. Connect both portals (see Connections)
  2. Create comparison: Production (source) → Staging (target)
  3. Wait for population to complete
  4. Review differences in diff viewer
  5. Select items to deploy
  6. Deploy changes to staging

Comparing Portal to Git​

Use case: Validate that portal matches your Git repository

  1. Connect HubSpot portal and GitHub repo
  2. Create comparison: Git (source) → Portal (target)
  3. Review differences
  4. Deploy missing items from Git to portal

Pre-Deployment Validation​

Use case: Check what will change before deploying

  1. Create comparison between environments
  2. Review all differences carefully
  3. Check for unexpected changes
  4. Rename comparison: "Pre-Deploy Check - [Date]"
  5. Keep for audit trail

Troubleshooting​

"New Comparison" Button Disabled​

Problem: Cannot create new comparison
Cause: Less than 2 sources configured

Solution:

  1. Connect at least 2 HubSpot portals, OR
  2. Connect at least 2 GitHub repositories, OR
  3. Connect 1 portal + 1 repository

See Connections and GitHub Integration.

Comparison Stuck in "Pending"​

Problem: Comparison status doesn't change from pending

Possible causes:

  • Worker not running
  • Task queue backed up
  • Connection authentication expired

Solution:

  1. Check connection status on Connections screen
  2. Re-authenticate if needed
  3. Wait a few minutes for task queue to process
  4. If still stuck after 10 minutes, delete and recreate

Population Taking Too Long​

Problem: Metadata extraction is slow

Factors affecting speed:

  • Number of metadata types
  • Amount of data in portal/repo
  • HubSpot API rate limits
  • Network conditions

Expected times:

  • Small portal (less than 100 items): 1-2 minutes
  • Medium portal (100-1000 items): 3-5 minutes
  • Large portal (more than 1000 items): 5-15 minutes

Solution: Be patient. The system will continue processing in the background.

Cannot Delete Comparison​

Problem: Delete button is disabled or missing

Cause: Insufficient permissions

Solution: Contact your workspace admin to grant comparisons:delete permission.

Source and Target Look Identical​

Problem: No differences shown, but you expected changes

Possible causes:

  • Environments are actually in sync
  • Metadata types not selected during extraction
  • Cached data from previous comparison

Solution:

  1. Click Refresh button to re-extract metadata
  2. Verify correct source and target are selected
  3. Check that relevant metadata types are enabled

Best Practices​

Organization​

  • Use descriptive names: Rename comparisons immediately after creation
  • Delete old comparisons: Clean up test or outdated comparisons regularly
  • Keep audit trail: Preserve important comparisons for compliance

Workflow​

  • Compare before deploying: Always create a comparison before major deployments
  • Review carefully: Check all differences before selecting items to deploy
  • Document changes: Use comparison names to document what was compared and when

Performance​

  • Limit concurrent comparisons: Don't create too many at once
  • Reuse comparisons: Refresh existing comparisons instead of creating new ones
  • Archive old data: Delete comparisons older than 90 days

Next Steps​