Skip to main content

Deployment History

Deployment History provides a complete audit trail of all deployments for a comparison. Every deployment is logged with detailed information about what was deployed, when, by whom, and whether it succeeded or failed.

Accessing Deployment History​

From Comparison View​

  1. Open a Comparison

    • Go to Comparisons → Select a comparison
    • Or create a new comparison

  2. Navigate to History Tab

    • Click the History tab at the top
    • The deployment history table appears

What You'll See​

The History tab shows all past deployments for this specific comparison, including:

  • When the deployment started
  • Current status (pending, in progress, completed, failed, partially deployed)
  • Success and failure counts
  • Missing OAuth scopes (if any)
  • Detailed logs for each deployment

Deployment Record Structure​

Each deployment record contains:

FieldDescriptionExample
IDUnique deployment identifierabc-123-def-456
Comparison IDThe comparison this deployment belongs tocomp-789
StatusCurrent deployment statuscompleted, failed, pending, in_progress, partially_deployed
Started AtWhen the deployment began2026-04-16 14:30:00 UTC
Finished AtWhen the deployment completed2026-04-16 14:32:15 UTC
Success CountNumber of items deployed successfully15
Fail CountNumber of items that failed to deploy2
Missing ScopesOAuth scopes required but not granted['automation.workflows.write']
LogsDetailed execution logsArray of log entries
Created AtWhen the deployment record was created2026-04-16 14:29:55 UTC

Deployment Statuses​

Pending​

Indicator: Blue badge with pulse animation
Meaning: Deployment has been queued but hasn't started yet

What's Happening:

  • The deployment record was created
  • A sync task was queued in the background
  • Waiting for the deployment worker to pick it up

Typical Duration: 1-5 seconds

In Progress​

Indicator: Blue badge with pulse animation
Meaning: Deployment is currently running

What's Happening:

  • The deployment worker is processing items
  • Items are being created, updated, or deleted in HubSpot
  • Progress is being logged in real-time

Typical Duration: 30 seconds to 5 minutes (depending on changeset size)

Completed​

Indicator: Green badge
Meaning: All items were deployed successfully

What's Happening:

  • All items in the changeset were deployed
  • No errors occurred
  • Success count equals the total number of items

Next Steps:

  • Verify the changes in HubSpot
  • Review the logs to confirm all items were deployed correctly

Failed​

Indicator: Red badge
Meaning: The deployment failed completely

What's Happening:

  • An error occurred that prevented the deployment from completing
  • No items were deployed (or very few)
  • Error details are in the logs

Common Causes:

  • Missing OAuth scopes
  • Invalid metadata (e.g., circular dependencies)
  • HubSpot API errors
  • Network issues

Next Steps:

  • Review the logs to identify the error
  • Fix the issue (e.g., reconnect with correct scopes)
  • Retry the deployment

Partially Deployed​

Indicator: Yellow badge
Meaning: Some items succeeded, others failed

What's Happening:

  • The deployment completed, but some items failed
  • Success count > 0 and fail count > 0
  • Partial progress was made

Common Causes:

  • Some items have missing dependencies
  • Some items require scopes that weren't granted
  • Some items have validation errors

Next Steps:

  • Review the logs to see which items failed
  • Fix the failing items
  • Use Assisted Deployment to retry only the failed items

Viewing Deployment Details​

Success and Failure Counts​

The Results column shows:

15 / 2
  • Green number (15) — Items deployed successfully
  • Red number (2) — Items that failed to deploy

Interpreting Results:

  • 10 / 0 — Perfect deployment, all items succeeded
  • 8 / 2 — Partial deployment, 8 succeeded, 2 failed
  • 0 / 10 — Complete failure, no items deployed

Missing Scopes​

The Missing Scopes column shows OAuth scopes that were required but not granted.

Example:

automation.workflows.write
crm.schemas.custom.write

What This Means:

  • The deployment tried to deploy workflows and custom objects
  • The connection doesn't have write permissions for these types
  • Items requiring these scopes were skipped or failed

How to Fix:

  1. Click View Scopes in the Instance Observer
  2. Note which scopes are missing
  3. Reconnect the portal and request the missing scopes
  4. Retry the deployment

See OAuth Scopes for details.

Deployment Logs​

Click View (X) in the Logs column to see detailed execution logs.

Log Entry Format:

[1] SUCCESS | custom_objects:projects | Created successfully
[2] SUCCESS | property:contacts:email | Updated successfully
[3] ERROR | workflow:12345678 | Missing scope: automation.workflows.write
[4] SUCCESS | pipeline:deals:default | Updated successfully

Log Entry Structure:

  • [Number] — Log entry index
  • Status — SUCCESS, ERROR, INFO
  • Item — Metadata type and name
  • Message — What happened

Color Coding:

  • Green — Success
  • Red — Error
  • Gray — Info

Using Logs for Troubleshooting:

  1. Look for ERROR entries
  2. Identify which items failed
  3. Read the error message
  4. Fix the issue and retry

Auto-Refresh​

The deployment history automatically refreshes every 5 seconds when there are active deployments (pending or in progress).

Why Auto-Refresh?

  • See real-time progress without manually refreshing
  • Know immediately when a deployment completes
  • Monitor long-running deployments

When It Stops:

  • All deployments are completed, failed, or partially deployed
  • No active deployments remain

Pagination​

The deployment history shows 10 deployments per page.

Navigation:

  • ← Previous — Go to the previous page
  • → Next — Go to the next page
  • Showing page X — Current page number

Why Pagination?

  • Keeps the UI fast and responsive
  • Prevents loading hundreds of deployments at once
  • Focuses on recent deployments

Common Workflows​

Workflow 1: Reviewing a Recent Deployment​

  1. Open the Comparison

    • Go to Comparisons → Select the comparison

  2. Navigate to History Tab

    • Click History

  3. Find the Recent Deployment

    • The most recent deployment is at the top
    • Check the status badge

  4. Review Results

    • Look at success/failure counts
    • If any failures, click View Logs

  5. Verify in HubSpot

    • Open your HubSpot portal
    • Navigate to the deployed items
    • Confirm they match expectations

Workflow 2: Troubleshooting a Failed Deployment​

  1. Identify the Failed Deployment

    • Look for the red "FAILED" badge

  2. Check Missing Scopes

    • Look at the Missing Scopes column
    • Note which scopes are required

  3. Review Logs

    • Click View Logs
    • Find ERROR entries
    • Read the error messages

  4. Fix the Issue

    • If missing scopes: Reconnect with correct scopes
    • If validation error: Fix the metadata in the source
    • If API error: Wait and retry

  5. Retry the Deployment

    • Go back to the Compare tab
    • Click Deploy Selected Items
    • Choose deployment mode and retry

Workflow 3: Comparing Two Deployments​

Scenario: You deployed the same changeset twice and want to compare results.

  1. Open History Tab

    • Navigate to the comparison
    • Click History

  2. Find Both Deployments

    • Identify the two deployments by timestamp
    • Note the status of each

  3. Compare Results

    • Look at success/failure counts
    • Check if missing scopes changed
    • Review logs for differences

  4. Analyze

    • Did the second deployment succeed where the first failed?
    • Were different items deployed?
    • Did you fix the issues between deployments?

Workflow 4: Auditing Deployment Activity​

Scenario: You want to see all deployments for a comparison over the past month.

  1. Open History Tab

    • Navigate to the comparison
    • Click History

  2. Browse Pages

    • Use pagination to view older deployments
    • Note the timestamps

  3. Export Data (Manual)

    • Take screenshots or notes
    • Export to CSV if needed (contact support for bulk export)

  4. Analyze Trends

    • How many deployments succeeded vs failed?
    • Are there recurring errors?
    • Which items fail most often?

Deployment Audit Trail​

Why Audit Trails Matter​

Deployment history provides a complete audit trail for:

  • Compliance — Prove when and what was deployed
  • Troubleshooting — Identify when issues were introduced
  • Accountability — See who deployed what and when
  • Rollback — Identify the last known good state

What's Logged​

Every deployment logs:

  • ✅ When — Exact timestamp of deployment start and finish
  • ✅ What — Which items were deployed (in logs)
  • ✅ How — Success or failure for each item
  • ✅ Why — Error messages for failures
  • ✅ Scopes — Which permissions were missing

What's NOT Logged​

  • ❌ Who — User who triggered the deployment (planned for future release)
  • ❌ Changeset — The exact changeset deployed (stored in comparison, not deployment record)
  • ❌ Before/After — Snapshots of metadata before and after deployment

Best Practices​

1. Review Deployment History After Each Deployment​

After deploying, always check the history tab to:

  • Confirm the deployment completed
  • Review success/failure counts
  • Check for missing scopes
  • Read the logs for any warnings

2. Keep Deployment History Clean​

Avoid creating unnecessary deployments:

  • Don't deploy empty changesets
  • Don't repeatedly deploy the same items
  • Use Assisted Deployment to retry only failed items

3. Document Failed Deployments​

When a deployment fails:

  • Take a screenshot of the logs
  • Document the error message
  • Note what you did to fix it
  • Share with your team

Regularly review deployment history to identify:

  • Recurring errors
  • Items that frequently fail
  • Missing scopes that need to be granted
  • Patterns in deployment timing

5. Use Deployment History for Rollback Planning​

Before deploying to production:

  • Note the current state in deployment history
  • Document the last successful deployment
  • Plan how to rollback if needed

Troubleshooting​

Deployment Not Appearing in History​

Cause: The deployment record wasn't created or the comparison ID is wrong.

Solution:

  1. Verify you're viewing the correct comparison
  2. Refresh the page
  3. Contact support if the issue persists

Deployment Stuck in "Pending"​

Cause: The deployment worker is not running or is overloaded.

Solution:

  1. Wait 1-2 minutes
  2. Check if the worker is running: 
    ps aux | grep deployWorker
  3. Restart the worker if needed: 
    npm run worker:deploy

Logs Not Showing​

Cause: The deployment completed but logs weren't saved.

Solution:

  • This is rare and usually indicates a worker crash
  • Check worker logs for errors
  • The deployment may have succeeded even without logs

Auto-Refresh Not Working​

Cause: JavaScript error or browser issue.

Solution:

  1. Open browser console (F12)
  2. Look for errors
  3. Refresh the page
  4. If issue persists, manually refresh every few seconds

Future Enhancements​

Planned Features​

  1. User Attribution

    • Track which user triggered each deployment
    • Show user avatar and name in history

  2. Changeset Snapshot

    • Store the exact changeset deployed
    • Allow viewing what was deployed without the comparison

  3. Before/After Snapshots

    • Capture metadata state before and after deployment
    • Enable one-click rollback

  4. Deployment Comments

    • Add notes to deployments
    • Document why a deployment was made

  5. Export to CSV

    • Export deployment history to CSV
    • Include all fields and logs

  6. Deployment Comparison

    • Compare two deployments side-by-side
    • See what changed between deployments

  7. Deployment Notifications

    • Get notified when a deployment completes
    • Receive alerts for failed deployments