Metadata Backups

Metadata Backups automatically export your HubSpot portal configuration (properties, workflows, forms, pipelines, etc.) and commit it to a Git repository on a schedule you define. Each backup run creates a new Git commit — giving you a full version history of your portal's structure.

Metadata vs. Data

• Metadata Backups (this page) — Export portal configuration and structure to Git
• Data Backups — Export CRM records (contacts, companies, deals) to CSV files

Creating a backup

1. Go to Backups in the sidebar
2. Click New Backup
3. Fill in the backup configuration:
   • HubSpot Portal — the source portal to back up
   • Repository — the target GitHub repository
   • Target Branch — the branch to commit to (defaults to the repo's default branch)
   • Schedule — how often to run the backup
4. Click Save

Schedule options

Frequency	Description	Configuration
hourly	Runs once per hour	Set the minute within the hour (e.g. :30)
daily	Runs once per day	Set the time in UTC (e.g. 02:00)
weekly	Runs once per week	Set the day of week and time in UTC

All times are in UTC.

Pausing and resuming

Use the toggle on a backup card to pause or resume a backup. Paused backups will not run until re-enabled. The status indicator shows Active or Paused.

Manual backup trigger

You can trigger a backup manually at any time, regardless of the schedule:

1. Go to the Backups page
2. Find the backup you want to run
3. Click Run Now on the backup card
4. The backup will start immediately

When to use manual triggers:

• Before making major changes to your portal
• To capture the current state immediately
• To test a new backup configuration
• After fixing an error to retry the backup

Manual backups don't affect the regular schedule - scheduled backups will continue to run as configured.

Backup run status

Each backup run goes through several states:

Status	Description	Duration
Pending	Backup is queued and waiting to start	Usually < 1 minute
Processing	Actively extracting metadata from HubSpot	2-10 minutes (depends on portal size)
Committing	Writing files and creating Git commit	< 1 minute
Completed	Backup finished successfully	-
Failed	Backup encountered an error	-

You can monitor the current status on the backup card. The status updates automatically every few seconds.

Backup error handling

If a backup fails, the system handles it gracefully:

Automatic retry

• Transient errors (network issues, rate limits) are retried automatically
• Up to 3 retry attempts with exponential backoff
• If all retries fail, the backup is marked as failed

Error notifications

When a backup fails:

• The backup card shows an error status
• An email notification is sent (if notifications are enabled)
• The error message is logged in the backup history

Common errors and solutions

"Failed to fetch metadata from HubSpot"

• Cause: HubSpot API is temporarily unavailable or rate limited
• Solution: Wait a few minutes and trigger manually, or wait for the next scheduled run

"Git push failed"

• Cause: Git repository is unavailable, branch is protected, or there's a merge conflict
• Solution: Check repository settings, verify branch permissions, resolve any conflicts

"Token expired or invalid"

• Cause: HubSpot connection token needs refresh
• Solution: The system will attempt automatic token refresh. If it fails, reconnect the portal.

"Missing required scopes"

• Cause: Connection doesn't have permissions to read certain metadata types
• Solution: Reconnect the portal and grant all requested scopes

Viewing error details

To see detailed error information:

1. Click History on the backup card
2. Find the failed run
3. Click to expand and view the full error message
4. Use the error message to diagnose and fix the issue

Recovering from errors

After fixing the underlying issue:

1. Click Run Now to trigger a manual backup
2. Verify the backup completes successfully
3. Scheduled backups will resume automatically

If errors persist:

• Check the connection status
• Verify repository access
• Review scope permissions
• Contact support if needed

Editing a backup

Click Edit on a backup card to change the schedule, target branch, or other settings. The portal and repository cannot be changed after creation — delete and recreate the backup if you need to change those.

Backup history

Click History on a backup card to view the run log. Each entry shows:

• Run timestamp
• Status (success, error, in progress)
• Error message (if applicable)

How backups are stored in Git

Each backup run creates a commit on the target branch with the following structure:

hubspot-metadata/
├── contacts/
│   ├── properties.json
│   └── property-groups.json
├── deals/
│   ├── properties.json
│   └── pipelines.json
├── workflows/
│   └── workflows.json
└── ...

The commit message includes the portal ID, timestamp, and backup ID for traceability.

Using backup history for rollback

Because backups are stored as Git commits, you can roll back to any previous state:

1. Find the commit you want to restore in your Git history
2. Create a new comparison using that commit's branch/tag as the source and your live portal as the target
3. Review the diff and create a deployment to apply the changes

tip

Tag important backup commits in Git (e.g. before-migration-2026-04) to make them easy to find later.