Connections

Connections are the foundation of HubSpot Deploy. You need at least one HubSpot connection and one GitHub connection to use backups, comparisons, and deployments.

HubSpot Connections

Connecting a portal

1. Go to Connections in the sidebar
2. Click Connect Portal
3. You'll be redirected to HubSpot's OAuth authorization page
4. Select the portal you want to connect and click Authorize
5. You'll be returned to HubSpot Deploy — the portal will appear in your connections list

HubSpot Deploy requests the following scopes:

• crm.objects.custom.read / write
• crm.schemas.custom.read / write
• crm.schemas.contacts.read
• crm.schemas.deals.read
• automation (workflows)
• forms

Metadata retrieval

After connecting, HubSpot Deploy retrieves your portal's metadata. The status indicator on the connection card shows the retrieval progress:

Status	Meaning
pending	Retrieval queued
in progress	Actively fetching metadata
completed	Metadata is up to date
error	Retrieval failed — check the connection

Renaming a portal

Hover over a connection card and click the pencil icon to give the portal a friendly label (e.g. "Production Portal"). This label appears throughout the app.

Metadata Explorer

Click View Metadata on a connection card to open the Metadata Explorer. You can browse all retrieved metadata objects, inspect individual records, and view the raw JSON using the Monaco editor.

Automatic token refresh

HubSpot OAuth tokens expire after a period of time. HubSpot Deploy automatically handles token refresh for you:

• Automatic detection - The system checks token expiration before every API call
• Proactive refresh - Tokens are refreshed when they have less than 5 minutes remaining
• Seamless operation - You never need to manually re-authenticate
• Background process - Refresh happens automatically without interrupting your work

If a token refresh fails (rare), you'll see an error status on the connection card. In this case, you may need to reconnect the portal.

Private App tokens don't expire and don't require refresh.

Deleting a connection

To remove a connection from HubSpot Deploy:

1. First, revoke access in HubSpot:

   • Go to your HubSpot account settings
   • Navigate to Integrations → Connected Apps
   • Find HubSpot Deploy and click Remove

2. Then, remove the connection from HubSpot Deploy:

   • Contact your workspace admin to delete the connection
   • This feature will be added to the UI in a future update

Important

Deleting a connection will:

• Remove all associated metadata from HubSpot Deploy
• Delete all comparisons that use this connection
• Remove all backup configurations for this portal
• Delete all deployment history for this portal

This action cannot be undone. Make sure you have backups of any important data before deleting a connection.

Permissions

Only workspace admins can create or delete connections. Members can view connections but cannot modify them.

GitHub Connections

Connecting GitHub

1. On the Connections page, click Connect Git
2. Authorize GitHub access via OAuth
3. Select the GitHub account or organization to connect

Adding a repository

After connecting GitHub, you need to add individual repositories:

1. Click Add Repo
2. Select the repository from the list
3. Choose the default branch

You can add multiple repositories from the same GitHub connection. Each repository can be used independently as a backup target or comparison source.

Repository status

Connected repositories show a Connected status indicator. If a repository is deleted or access is revoked on GitHub, the status will update to reflect the error.

Troubleshooting

Connection stuck in "pending" status

Cause: The metadata extraction worker hasn't picked up the job yet, or there's a backlog.

Solution:

• Wait 1-2 minutes - extraction usually starts automatically
• Refresh the page to see updated status
• If stuck for more than 5 minutes, contact support

Connection shows "error" status

Possible causes:

• HubSpot API is temporarily unavailable
• Token has been revoked in HubSpot
• Missing required scopes
• Network connectivity issues

Solution:

1. Check the connection card for error details
2. Try reconnecting the portal
3. Verify the portal is accessible in HubSpot
4. Check that you haven't revoked access in HubSpot settings

"Some requested permissions were not granted"

Cause: During OAuth authorization, you didn't grant all requested scopes.

Impact:

• You can still read metadata
• Some deployment operations may fail
• Certain metadata types may not be accessible

Solution:

1. Note which scopes were denied
2. Reconnect the portal
3. Grant all requested permissions during authorization
4. See Scopes Reference for details on what each scope enables

Token refresh failed

Cause: The refresh token is invalid or has been revoked.

Solution:

• Reconnect the portal to get a fresh token
• This will require re-authorizing in HubSpot

Repository not showing up

Cause: The repository may not be accessible with your GitHub token, or it hasn't been added yet.

Solution:

1. Verify you've clicked Add Repo after connecting GitHub
2. Check that the repository exists and you have access
3. Try reconnecting GitHub if the repository still doesn't appear

Can't connect portal (workspace member)

Cause: Only workspace admins can create connections.

Solution:

• Ask a workspace admin to connect the portal
• Or request admin role from the workspace owner

Connection status reference

Status	Meaning	Action Needed
Pending	Extraction queued	Wait - usually starts within 1 minute
In Progress	Actively fetching metadata	Wait - can take 2-10 minutes depending on portal size
Completed	Metadata is up to date	None - connection is ready to use
Error	Retrieval failed	Check error message, try reconnecting

Best practices

Use descriptive labels

Rename your connections with clear labels:

• ✅ "Production Portal"
• ✅ "Staging Environment"
• ✅ "Client ABC - Main"
• ❌ "HubSpot Portal" (default, not descriptive)

Monitor connection status

Check connection status regularly:

• Ensure metadata extraction completes successfully
• Watch for scope mismatch warnings
• Verify tokens are refreshing automatically

Keep access current

• Don't revoke access in HubSpot without deleting the connection in HubSpot Deploy
• Reconnect if you see persistent errors
• Update scopes if you need access to new metadata types

Organize by workspace

Use workspaces to organize connections:

• Production portals in one workspace
• Development/staging in another
• Client portals in separate workspaces

This keeps your connections organized and prevents accidental deployments to the wrong portal.

Related features

• Scopes Reference - Understanding HubSpot API scopes
• Workspaces - Organizing connections by workspace
• Permissions - Who can manage connections
• Instance Observer - View detailed connection information