Skip to main content

Assisted Deployment

Assisted Deployment is a step-by-step deployment mode that gives you full control over complex migrations. Instead of deploying all changes at once, the system breaks the deployment into logical stages and pauses after each one, allowing you to manually verify the results in HubSpot before proceeding.

When to Use Assisted Deployment​

✅ Use Assisted Deployment For:​

  • Production deployments where you need to verify each stage
  • Complex migrations with many interdependent metadata items
  • High-risk changes like custom object schema modifications
  • First-time deployments to a new portal
  • Troubleshooting failed auto-deployments by deploying in smaller batches
  • Learning how HubSpot Deploy handles different metadata types

⚡ Use Auto Deployment For:​

  • Development/sandbox environments where speed matters
  • Simple changes with few items (e.g., updating a few properties)
  • Trusted workflows that have been tested before
  • CI/CD pipelines where manual intervention isn't practical

How Assisted Deployment Works​

1. Deployment Stages​

Assisted Deployment breaks your changeset into logical stages based on metadata type and operation:

Stage 1: Create custom_objects (3 items)
Stage 2: Update standard_objects (12 items)
Stage 3: Create workflows (5 items)
Stage 4: Update pipelines (2 items)
...

Each stage groups items by:

  • Metadata Type (e.g., custom_objects, workflows, forms)
  • Operation (create, update, delete)

This ensures that dependencies are respected and related items are deployed together.

2. Step-by-Step Execution​

For each stage, the process is:

  1. Review — See what will be deployed in this stage
  2. Deploy — Click "Deploy Step" to execute
  3. Verify — Check HubSpot to confirm the changes are correct
  4. Proceed — Click "Verified, Proceed to Next Step"

If something goes wrong, you can:

  • Retry — Re-run the stage (only failed items will be retried)
  • Skip — Skip the stage and move to the next one
  • Cancel — Stop the entire deployment process

3. Automatic Retry Logic​

If a stage fails partially (some items succeed, others fail):

  • ✅ Successfully deployed items are tracked and won't be re-deployed
  • ❌ Failed items can be retried after you fix the issue in HubSpot
  • 🔄 The "Retry Remaining" button only deploys items that haven't succeeded yet

This prevents duplicate items and allows you to fix issues incrementally.

Using Assisted Deployment​

Starting an Assisted Deployment​

  1. Create or Open a Comparison

    • Go to Comparisons → Select a comparison
    • Review the diff and select items to deploy

  2. Choose Deployment Mode

    • Click Deploy Selected Items
    • A modal appears: "Choose Deployment Mode"
    • Click Assisted Deploy (Step-by-Step)

  3. Review Deployment Plan

    • The system generates a deployment plan with stages
    • Each stage shows:
      • Metadata type and operation
      • Number of items
      • Current status (pending, running, success, error, skipped)

Executing Each Stage​

Stage Status Indicators​

StatusIconMeaning
PendingNumber (1, 2, 3...)Stage hasn't started yet
RunningSpinnerStage is currently deploying
Success✓ Green checkmarkStage completed successfully
Error⚠ Red exclamationStage failed (some or all items)
Skipped→ Forward arrowStage was manually skipped

Deploying a Stage​

  1. Click "Deploy Step X"

    • The stage status changes to "Running"
    • Items are deployed to HubSpot in the background
    • Progress is shown in real-time

  2. Wait for Completion

    • If successful: Status changes to "Success"
    • If failed: Status changes to "Error"

  3. Verify in HubSpot

    • Open your HubSpot portal in a new tab
    • Navigate to the relevant section (e.g., Settings → Objects → Custom Objects)
    • Confirm the changes are correct

  4. Proceed or Retry

    • If everything looks good: Click "Verified, Proceed to Next Step"
    • If something failed: Click "Retry Remaining" after fixing the issue
    • If you want to skip: Click "Skip Step"

Handling Failures​

Partial Failures​

If some items in a stage succeed and others fail:

  1. Review the Error

    • The stage status shows "Failed"
    • Check the deployment logs for details

  2. Fix the Issue

    • Common issues:
      • Missing dependencies (e.g., a property references a non-existent property group)
      • Invalid data (e.g., a workflow references a deleted list)
      • Permission errors (e.g., missing OAuth scopes)
    • Fix the issue directly in HubSpot or by updating the source data

  3. Retry Remaining Items

    • Click "Retry Remaining (X)"
    • Only items that haven't succeeded will be re-deployed
    • Successfully deployed items are not duplicated

Example: Custom Object Deployment Failure​

Scenario: You're deploying 5 custom objects. 3 succeed, 2 fail due to invalid property types.

What Happens:

  • Stage status: "Error"
  • Successfully deployed: 3 objects (tracked internally)
  • Failed: 2 objects

Resolution:

  1. Review the error logs to identify which objects failed
  2. Fix the property type issues in the source data (Git or source portal)
  3. Click "Retry Remaining (2)"
  4. Only the 2 failed objects are re-deployed
  5. Stage status changes to "Success"

Skipping Stages​

You can skip a stage if:

  • The items in that stage are not critical
  • You want to deploy them manually later
  • The stage keeps failing and you want to proceed with the rest

To Skip a Stage:

  1. Click "Skip Step"
  2. The stage status changes to "Skipped"
  3. Click "Verified, Proceed to Next Step" to continue
warning

Skipped items are not deployed. If other stages depend on them, those stages may also fail.

Assisted Deployment vs. Auto Deployment​

FeatureAssisted DeploymentAuto Deployment
ExecutionStep-by-step with manual verificationFully automated
ControlHigh — pause, verify, retry, skipLow — runs to completion
SpeedSlower (requires manual intervention)Faster (no waiting)
VisibilityHigh — see each stage as it happensMedium — view logs after completion
Error HandlingRetry individual stagesRetry entire deployment
Best ForProduction, complex migrations, learningDevelopment, simple changes, CI/CD
Dependency ResolutionGrouped by type and operationFully automatic with dependency graph

Best Practices​

1. Use Assisted Deployment for Production​

Always use Assisted Deployment for production environments. The ability to verify each stage reduces the risk of breaking changes.

2. Review the Deployment Plan First​

Before starting, review the entire deployment plan:

  • Check the number of stages
  • Verify the order makes sense (e.g., custom objects before properties)
  • Estimate how long it will take (each stage requires manual verification)

3. Keep HubSpot Open in Another Tab​

Open your HubSpot portal in a separate browser tab before starting. This makes verification faster and easier.

4. Don't Rush Verification​

Take time to verify each stage properly:

  • Check that items were created/updated correctly
  • Verify relationships (e.g., properties are in the correct groups)
  • Test functionality (e.g., workflows trigger as expected)

5. Document Failures​

If a stage fails, document:

  • Which items failed
  • The error message
  • How you fixed it

This helps with troubleshooting future deployments.

6. Use Skip Sparingly​

Only skip stages if you're certain the items aren't needed. Skipped items can cause dependency errors in later stages.

7. Test in Sandbox First​

Before deploying to production, test the same changeset in a sandbox portal using Assisted Deployment. This helps you identify issues early.

Common Scenarios​

Scenario 1: Deploying a New Custom Object with Properties​

Deployment Plan:

Stage 1: Create custom_objects (1 item) — "Project" object
Stage 2: Create standard_objects (15 items) — Properties for "Project"
Stage 3: Create association_definitions (2 items) — Associate "Project" with "Contact" and "Deal"

Execution:

  1. Stage 1: Deploy the "Project" custom object

    • Verify: Go to HubSpot → Settings → Objects → Custom Objects
    • Confirm "Project" object exists
    • Proceed to Stage 2

  2. Stage 2: Deploy 15 properties for "Project"

    • Verify: Open "Project" object → Properties tab
    • Confirm all 15 properties are present
    • Proceed to Stage 3

  3. Stage 3: Deploy association definitions

    • Verify: Check that "Project" can be associated with "Contact" and "Deal"
    • Finish deployment

Scenario 2: Updating Workflows with Dependencies​

Deployment Plan:

Stage 1: Update hubspot_lists (3 items) — Lists used by workflows
Stage 2: Update workflows (5 items) — Workflows that reference the lists

Execution:

  1. Stage 1: Deploy list updates

    • Verify: Go to HubSpot → Lists
    • Confirm lists are updated correctly
    • Proceed to Stage 2

  2. Stage 2: Deploy workflow updates

    • Failure: 2 workflows fail because they reference a list that doesn't exist
    • Fix: Create the missing list manually in HubSpot
    • Retry: Click "Retry Remaining (2)"
    • Success: All workflows deploy successfully
    • Finish deployment

Scenario 3: Migrating Between Portals​

Deployment Plan:

Stage 1: Create custom_objects (3 items)
Stage 2: Create standard_objects (50 items)
Stage 3: Create property_groups (8 items)
Stage 4: Create pipelines (4 items)
Stage 5: Create workflows (12 items)
Stage 6: Create forms (6 items)

Execution:

  • Deploy each stage one at a time
  • Verify thoroughly after each stage
  • If any stage fails, fix the issue and retry
  • Document any manual adjustments needed
  • Total time: ~30-45 minutes (depending on verification speed)

Troubleshooting​

Deployment Stuck on "Running"​

Cause: The background worker may be overloaded or the HubSpot API is slow.

Solution:

  • Wait 5-10 minutes
  • If still stuck, refresh the page
  • Check the deployment history to see if it completed

"Retry Remaining" Shows 0 Items​

Cause: All items in the stage have already succeeded.

Solution:

  • Click "Verified, Proceed to Next Step" to continue
  • The stage is effectively complete

Stage Fails with "Missing Dependency"​

Cause: An item in this stage references another item that doesn't exist yet.

Solution:

  1. Check the error logs to identify the missing dependency
  2. Either:
    • Deploy the dependency manually in HubSpot
    • Go back and deploy an earlier stage that creates the dependency
  3. Retry the stage

Can't Proceed After Skipping a Stage​

Cause: Later stages depend on items from the skipped stage.

Solution:

  • Go back and deploy the skipped stage
  • Or manually create the missing items in HubSpot
  • Then retry the failing stage

Security & Permissions​

Who Can Use Assisted Deployment?​

Only workspace admins can create deployments (both assisted and auto). See Permissions for details.

OAuth Scopes​

Assisted Deployment requires the same OAuth scopes as Auto Deployment. If you're missing write permissions for a metadata type, those items will be skipped automatically. See OAuth Scopes for details.

FAQ​

Can I pause an Assisted Deployment and resume later?​

No. Once you start an Assisted Deployment, you must complete it or cancel it. If you cancel, you'll need to start over from the beginning.

What happens if I close the browser during Assisted Deployment?​

The current stage will continue running in the background, but you won't be able to see the progress or proceed to the next stage. You'll need to start a new deployment.

Can I switch from Assisted to Auto Deployment mid-process?​

No. Once you choose a deployment mode, you must complete the deployment in that mode.

How long does Assisted Deployment take?​

It depends on:

  • Number of stages (typically 3-10)
  • Number of items per stage
  • How long you take to verify each stage

Typical range: 15-60 minutes for a full migration.

Can I automate Assisted Deployment?​

No. Assisted Deployment requires manual verification at each stage. For automation, use Auto Deployment instead.