Skip to main content

GitHub Integration

Connect your GitHub repositories to enable version-controlled metadata management, automated drift detection, and seamless deployments between Git and HubSpot.

Overview​

GitHub integration allows you to:

  • Store metadata in Git: Version-control your HubSpot metadata
  • Compare Git to HubSpot: See differences between your repository and portals
  • Deploy from Git: Push metadata changes from Git to HubSpot
  • Automated drift detection: Monitor when portals diverge from Git
  • Backup to Git: Automatically commit portal changes to your repository

Prerequisites​

Before connecting GitHub, you need:

  1. GitHub Account: Personal or organization account
  2. Personal Access Token (PAT): Token with repository access
  3. Repository: Existing repository or create a new one
  4. Permissions: git:create permission in your workspace

Creating a Personal Access Token​

  1. Go to GitHub → Settings → Developer settings
  2. Click Personal access tokens → Tokens (classic)
  3. Click Generate new token (classic)
  4. Configure the token:
    • Note: "HubSpot Deploy Integration"
    • Expiration: Choose duration (90 days recommended)
    • Scopes: Select repo (full control of private repositories)
  5. Click Generate token
  6. Copy the token immediately (you won't see it again)

Fine-Grained Token (Alternative)​

  1. Go to GitHub → Settings → Developer settings
  2. Click Personal access tokens → Fine-grained tokens
  3. Click Generate new token
  4. Configure the token:
    • Token name: "HubSpot Deploy Integration"
    • Expiration: Choose duration
    • Repository access: Select specific repositories
    • Permissions:
      • Contents: Read and write
      • Metadata: Read-only
  5. Click Generate token
  6. Copy the token immediately

⚠️ Security Note: Store your token securely. Never commit it to Git or share it publicly.

Connecting GitHub Account​

Step 1: Connect Your GitHub Account​

  1. Navigate to Connections screen
  2. In the Git Repositories column, click Connect Git
  3. In the modal:
    • (Optional) Enter Account Name Alias (e.g., "My Git Account")
    • Paste your Personal Access Token
  4. Click Connect Git

The system will:

  • Validate the token
  • Fetch your GitHub username
  • Store the connection securely (token is encrypted)
  • Enable repository management

Step 2: Add a Repository​

After connecting your GitHub account:

  1. Click Add Repo button
  2. In the modal:
    • Select GitHub Account from dropdown
    • Enter Repository in owner/repo format (e.g., acme/hubspot-metadata)
    • Enter Branch (default: main)
  3. Click Add Repository

The system will:

  • Validate repository access
  • Create repository record
  • Enable the repository for comparisons and deployments

Repository Format​

Directory Structure​

Your repository should follow this structure:

my-hubspot-metadata/
├── workflows/
│   ├── workflow-1.json
│   └── workflow-2.json
├── forms/
│   ├── contact-form.json
│   └── newsletter-form.json
├── emails/
│   ├── welcome-email.json
│   └── follow-up-email.json
├── custom_objects/
│   └── my-object.json
└── properties/
    ├── contact-properties.json
    └── company-properties.json

Metadata File Format​

Each metadata item is stored as a JSON file:

{
  "id": "12345",
  "name": "Contact Form",
  "type": "form",
  "properties": {
    "formType": "HUBSPOT",
    "submitText": "Submit",
    "redirect": "https://example.com/thank-you"
  },
  "fields": [
    {
      "name": "email",
      "label": "Email Address",
      "fieldType": "email",
      "required": true
    }
  ]
}

Note: The exact structure depends on the metadata type. Use the Backup feature to see the format for each type.

Using GitHub Integration​

Comparing Git to HubSpot​

Use case: See what's different between your repository and portal

  1. Navigate to Comparisons screen
  2. Click New Comparison
  3. Select:
    • Source: Your Git repository
    • Target: HubSpot portal
  4. Click Initialize Comparison
  5. Wait for population to complete
  6. Review differences in the diff viewer

Deploying from Git to HubSpot​

Use case: Push metadata changes from Git to your portal

  1. Create a comparison (Git → HubSpot)
  2. Review the differences
  3. Select items to deploy
  4. Click Deploy Selected
  5. Choose deployment mode (Auto or Assisted)
  6. Monitor deployment progress

See Deployments for detailed deployment instructions.

Backing Up HubSpot to Git​

Use case: Commit portal changes to your repository

  1. Navigate to Backups screen
  2. Select your HubSpot connection
  3. Choose metadata types to backup
  4. Select Git Repository as destination
  5. Click Start Backup

The system will:

  • Extract metadata from HubSpot
  • Format as JSON files
  • Commit to your repository
  • Push to the specified branch

See Backups for more details.

Automated Drift Detection​

Use case: Monitor when portal diverges from Git

  1. Navigate to Instance Observer for your portal
  2. Go to Drift Detection tab
  3. Click Configure Drift Detection
  4. Select:
    • Git Repository as source
    • Schedule (hourly, daily, weekly)
  5. Click Save

The system will:

  • Automatically compare Git to portal on schedule
  • Create drift reports when differences are found
  • Send email notifications (if configured)

See Drift Detection for more details.

Managing Repositories​

Viewing Repository Details​

  1. Navigate to Connections screen
  2. Find the repository in the Git Repositories column
  3. Click on the repository card

This shows:

  • Repository name and branch
  • Connected GitHub account
  • Recent comparisons using this repository
  • Deployment history

Removing a Repository​

⚠️ Warning: Removing a repository will:

  • Delete the repository record
  • Preserve existing comparisons and deployments
  • Disable drift detection using this repository

To remove:

  1. Navigate to repository details
  2. Click Remove Repository
  3. Confirm deletion

Updating Repository Branch​

To change the branch:

  1. Remove the existing repository
  2. Add it again with the new branch

Note: This creates a new repository record. Existing comparisons will reference the old record.

Multiple GitHub Accounts​

You can connect multiple GitHub accounts to access repositories from different organizations:

  1. Connect first account: Connect Git → Enter PAT
  2. Connect second account: Connect Git → Enter different PAT
  3. When adding repositories, select the appropriate account

Use cases:

  • Personal and work accounts
  • Multiple organizations
  • Different permission levels

Permissions​

GitHub integration requires workspace permissions:

ActionRequired Permission
Connect GitHub accountgit:create
Add repositorygit:create
View repositoriesgit:read
Remove repositorygit:delete
Deploy from Gitdeployments:create

Note: Workspace admins have all permissions by default.

Troubleshooting​

"Failed to connect" Error​

Problem: Cannot connect GitHub account

Possible causes:

  • Invalid or expired token
  • Insufficient token permissions
  • Network connectivity issues

Solution:

  1. Verify token is copied correctly (no extra spaces)
  2. Check token hasn't expired
  3. Ensure token has repo scope (classic) or Contents: Read and write (fine-grained)
  4. Generate a new token if needed

"Repository not found" Error​

Problem: Cannot add repository

Possible causes:

  • Repository name format incorrect
  • Token doesn't have access to repository
  • Repository doesn't exist
  • Private repository without proper permissions

Solution:

  1. Verify format is owner/repo (e.g., acme/metadata)
  2. Check repository exists on GitHub
  3. Ensure token has access to the repository
  4. For organization repos, verify token has organization access

"Failed to fetch metadata" During Comparison​

Problem: Comparison fails when reading from Git

Possible causes:

  • Branch doesn't exist
  • No metadata files in repository
  • Invalid JSON format in files
  • Token permissions revoked

Solution:

  1. Verify branch exists in repository
  2. Check repository has metadata files in correct format
  3. Validate JSON files are properly formatted
  4. Re-authenticate GitHub connection if token expired

Drift Detection Not Running​

Problem: Scheduled drift checks aren't executing

Possible causes:

  • Repository connection removed
  • Token expired
  • Worker not running
  • Schedule not configured

Solution:

  1. Check repository still exists in Connections
  2. Verify GitHub connection is active
  3. Re-configure drift detection schedule
  4. Check drift reports for error messages

Deployment from Git Fails​

Problem: Cannot deploy metadata from Git to HubSpot

Possible causes:

  • HubSpot connection expired
  • Insufficient HubSpot scopes
  • Invalid metadata format in Git
  • Dependency issues

Solution:

  1. Re-authenticate HubSpot connection
  2. Check HubSpot connection has required scopes (see Scopes)
  3. Validate metadata JSON files match expected format
  4. Review deployment logs for specific errors

Best Practices​

Token Management​

  • Use descriptive names: Name tokens clearly (e.g., "HubSpot Deploy - Production")
  • Set expiration: Use 90-day expiration and rotate regularly
  • Limit scope: Use fine-grained tokens for specific repositories when possible
  • Revoke unused tokens: Remove tokens you're no longer using

Repository Organization​

  • One repo per environment: Separate repos for production, staging, development
  • Use branches: Use Git branches for different environments or versions
  • Commit messages: Write clear commit messages when backing up to Git
  • Review changes: Always review Git diffs before deploying

Workflow​

  • Git as source of truth: Keep Git as the authoritative source for metadata
  • Regular backups: Schedule automatic backups from HubSpot to Git
  • Drift monitoring: Enable drift detection to catch manual portal changes
  • Test deployments: Test Git deployments in staging before production

Security​

  • Never commit tokens: Don't store PATs in your repository
  • Use .gitignore: Exclude sensitive files from Git
  • Rotate tokens: Change tokens every 90 days
  • Audit access: Regularly review who has access to repositories

Common Workflows​

Initial Setup: Portal to Git​

Goal: Start version-controlling an existing portal

  1. Connect GitHub account
  2. Create new repository on GitHub
  3. Add repository in HubSpot Deploy
  4. Create backup: Portal → Git
  5. Verify files committed to repository
  6. Enable drift detection

Continuous Deployment: Git to Portal​

Goal: Deploy metadata changes from Git

  1. Make changes to metadata files in Git
  2. Commit and push to repository
  3. Create comparison: Git → Portal
  4. Review differences
  5. Deploy selected items
  6. Verify changes in HubSpot

Environment Promotion: Staging to Production​

Goal: Promote tested changes to production

  1. Deploy changes to staging portal
  2. Test thoroughly in staging
  3. Backup staging portal to Git (staging branch)
  4. Create comparison: Git (staging) → Production Portal
  5. Review and deploy to production

Next Steps​