開発環境・CLI・デプロイワークフロー

HubSpot CLI のセットアップと認証

HubSpot CLI（コマンドラインインターフェース）は、 ローカルのファイルシステムとHubSpotポータルを双方向に同期するツールです。 デザインマネージャーをブラウザ上で操作するより、 エディタとターミナルで高速に開発できるのが最大のメリットです。

① Node.js とCLIのインストール

# Node.js 20以上が必要（v8.0.0以降は必須）。バージョン確認
$ node --version
v20.x.x  ← 20以上であること（18.x は NG）

# npmでHubSpot CLIをグローバルインストール
$ npm install -g @hubspot/cli

# インストール確認（v8.0.0以上を推奨）
$ hs --version
8.x.x

# または npx で都度実行（インストール不要）
$ npx @hubspot/cli --version

② 認証の設定（初回のみ）

# プロジェクトルートで初期化
$ hs init

# 対話形式で設定が進む
? Enter a name for this account (e.g. "my-sandbox"): my-company-dev
? Enter your HubSpot portal ID: 12345678
? How would you like to authenticate your account?
  ❯ Personal Access Key (recommended)
    OAuth2

# Personal Access Key を選択すると、ブラウザが開き
# HubSpot管理画面で Personal Access Key を発行できる
# Developer Accounts → アカウント → Personal Access Keys から取得

? Enter your personal access key: eu1-xxxx-xxxx-xxxx-xxxx
✔ Authenticated account: my-company-dev (12345678)
✔ Config file created: ~/.config/@hubspot/cli/config.yml

③ プロジェクト用の設定ファイル確認

hs init を実行すると、プロジェクトルートに hubspot.config.yml が生成されます。 このファイルがCLIの設定の起点になります。

defaultPortal: my-company-dev
portals:
  - name: my-company-dev
    portalId: 12345678
    authType: personalaccesskey
    personalAccessKey: eu1-xxxx-xxxx-xxxx-xxxx
    auth:
      tokenInfo:
        accessToken: CJa...
        expiresAt: '2024-12-31T00:00:00.000Z'

CLI 全コマンドリファレンス

旧コマンド → 新コマンド 対応表

主要コマンド一覧（v8 新体系）

コマンドの実践的な使い方（v8 対応）

# ===== テーマ全体のアップロード =====
$ hs cms upload ./src/my-theme @my-theme --portal=my-company-dev

# ===== 開発中のwatchモード起動 =====
$ hs cms watch ./src/my-theme @my-theme --portal=my-company-dev
Watcher started, watching "./src/my-theme"
Uploaded "templates/page.html" to "@my-theme/templates/page.html"
Uploaded "modules/hero-banner.module/module.html"

# ===== HubSpotから最新を取得（差分確認前）=====
$ hs cms fetch @my-theme ./src/my-theme-remote --portal=my-company-prod --overwrite

# ===== デプロイ前の lint チェック =====
$ hs cms lint ./src/my-theme --portal=my-company-dev
✔ No lint errors found

# ===== 特定のファイルのみアップロード =====
$ hs cms upload ./src/my-theme/modules/hero-banner.module @my-theme/modules/hero-banner.module

# ===== 新しいモジュールの雛形生成 =====
$ hs cms module pricing-table --path=./src/my-theme/modules
✔ Created "pricing-table.module" at ./src/my-theme/modules/pricing-table.module

# ===== ポータルのファイル一覧確認 =====
$ hs cms list --portal=my-company-prod
@my-theme/
├── templates/
├── modules/
├── css/
├── js/
└── theme.json

hs cms lint の活用

$ hs cms lint ./src/my-theme

✖ Error in "templates/blog-post.html" line 42:
  Unexpected tag: endmodule (did you mean end_module?)

⚠ Warning in "modules/card-grid.module/module.html" line 18:
  Variable "module.subtitle" used but not defined in fields.json

Lint complete: 1 error, 1 warning

# エラーを修正後に再実行
$ hs cms lint ./src/my-theme
✔ No lint errors found (1 warning)

ローカル開発フロー（watch モード）

実務での開発は hs cms watch を起動した状態でエディタを使います。 ファイルを保存するたびに自動でHubSpotにアップロードされ、 ブラウザをリロードすれば即座に確認できます。

推奨ディレクトリ構成

my-project/
├── src/                         # ← CLIで同期するファイル群
│   └── my-theme/               # テーマ本体
│       ├── theme.json
│       ├── templates/
│       ├── modules/
│       ├── css/
│       ├── js/
│       └── images/
├── .gitignore
├── .hsignore                    # CLIが無視するファイルを定義
├── hubspot.config.yml           # 認証設定（.gitignoreに追加）
├── package.json                  # npm scripts で開発コマンドを定義
└── README.md                    # セットアップ手順のドキュメント

package.json でコマンドを整理する

{
  "name": "my-company-hubspot",
  "version": "1.0.0",
  "scripts": {

    // ===== 開発コマンド =====
    "dev": "hs cms watch src/my-theme @my-theme --portal=dev",
    // npm run dev で watch モード起動（devポータルに同期）

    // ===== デプロイコマンド =====
    "deploy:dev"  : "hs cms upload src/my-theme @my-theme --portal=dev --overwrite",
    "deploy:prod" : "hs cms upload src/my-theme @my-theme --portal=prod --overwrite",

    // ===== チェックコマンド =====
    "lint"       : "hs cms lint src/my-theme --portal=dev",
    "fetch:prod"  : "hs cms fetch @my-theme src/my-theme-remote --portal=prod --overwrite",

    // ===== 複合コマンド =====
    "predeploy:prod": "npm run lint"
    // deploy:prodの前にlintを自動実行（エラーがあればデプロイを中断）
  },
  "devDependencies": {
    "@hubspot/cli": "^8.0.0"
    // CLI v8以上を指定（Node.js 20必須）
  }
}

# === 毎日の開発開始時 ===
$ npm run dev
Watcher started, watching "src/my-theme"
# エディタでファイルを編集 → 保存 → 自動アップロード → ブラウザでリロード確認

# === 作業が終わったら watch を Ctrl+C で停止 ===

# === 本番デプロイ前のチェック ===
$ npm run lint
✔ No lint errors found

# === 本番デプロイ（lintが通った場合のみ実行される）===
$ npm run deploy:prod
Uploading "src/my-theme" to "@my-theme" on portal "prod"...
✔ Done uploading 48 files

複数ポータルの管理戦略（開発・本番分離）

実案件では開発用ポータル（Sandbox/Developer Account）と 本番ポータルを分離して管理します。 本番環境に直接 watch することは事故の原因になるため厳禁です。

ポータル構成の全体像

複数ポータルの hubspot.config.yml 設定

# デフォルトポータル（hs cms upload で --portal を省略した場合に使われる）
defaultPortal: dev

portals:
  # ===== 開発ポータル（日常開発用）=====
  - name: dev
    portalId: 11111111
    authType: personalaccesskey
    personalAccessKey: eu1-dev-key-xxxxxxxxxx

  # ===== 本番ポータル（デプロイ時のみ）=====
  - name: prod
    portalId: 22222222
    authType: personalaccesskey
    personalAccessKey: eu1-prod-key-xxxxxxxxxx

  # ===== クライアント検証用（任意）=====
  - name: staging
    portalId: 33333333
    authType: personalaccesskey
    personalAccessKey: eu1-staging-key-xxxxxxxxxx

ポータル別の運用ルール

.hsignore による同期除外設定

.hsignore ファイルは .gitignore と同じ形式で、 hs cms upload や hs cms watch で同期しないファイル・ディレクトリを指定します。

hubl.config.yml の詳細設定

hubspot.config.yml には認証情報以外にも、 CLIの動作を細かくカスタマイズするオプションがあります。

defaultPortal: dev

# ===== CLIのグローバル設定 =====
httpTimeout: 30000
# APIリクエストのタイムアウト時間（ミリ秒）
# 大きなテーマをアップロードする際はこの値を増やす

allowUsageTracking: false
# HubSpotへの使用状況データ送信の許否

portals:
  - name: dev
    portalId: 11111111
    authType: personalaccesskey
    personalAccessKey: eu1-dev-key

    # ===== ポータル個別設定 =====
    defaultMode: write
    # write（アップロード優先）/ read（ダウンロード優先）

  - name: prod
    portalId: 22222222
    authType: personalaccesskey
    personalAccessKey: eu1-prod-key
    defaultMode: write

GitHub との連携と GitHub Actions CI/CD

Git リポジトリと GitHub Actions を連携させることで、 「mainブランチにマージされたら自動で本番デプロイ」 という CI/CD パイプラインを構築できます。

ブランチ戦略

GitHub Secrets の設定

Personal Access Key を GitHub リポジトリの Secrets に登録します。 GitHub のリポジトリページ → Settings → Secrets and variables → Actions から設定します。

GitHub Actions ワークフローの実装

name: Deploy to Dev Portal

on:
  push:
    branches:
      - develop

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install HubSpot CLI
        run: npm install -g @hubspot/cli

      - name: Create HubSpot config
        # Secretsから hubspot.config.yml を動的生成
        run: |
          cat > hubspot.config.yml << EOF
          defaultPortal: dev
          portals:
            - name: dev
              portalId: ${{ secrets.HUBSPOT_PORTAL_ID_DEV }}
              authType: personalaccesskey
              personalAccessKey: ${{ secrets.HUBSPOT_ACCESS_KEY_DEV }}
          EOF

      - name: Lint check
        run: hs cms lint src/my-theme --portal=dev

      - name: Deploy to Dev
        run: hs cms upload src/my-theme @my-theme --portal=dev --overwrite

      - name: Notify Slack on success
        if: success()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "✅ 開発環境へのデプロイ完了: ${{ github.event.head_commit.message }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

name: Deploy to Production

on:
  push:
    branches:
      - main

jobs:
  lint:
    name: Lint Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g @hubspot/cli
      - name: Create config
        run: |
          cat > hubspot.config.yml << EOF
          defaultPortal: dev
          portals:
            - name: dev
              portalId: ${{ secrets.HUBSPOT_PORTAL_ID_DEV }}
              authType: personalaccesskey
              personalAccessKey: ${{ secrets.HUBSPOT_ACCESS_KEY_DEV }}
          EOF
      - run: hs cms lint src/my-theme --portal=dev

  deploy:
    name: Deploy to Production
    needs: lint        # lint job が成功した場合のみ実行
    runs-on: ubuntu-latest
    environment: production   # GitHub Environments で承認ゲートを設定可能

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g @hubspot/cli

      - name: Create production config
        run: |
          cat > hubspot.config.yml << EOF
          defaultPortal: prod
          portals:
            - name: prod
              portalId: ${{ secrets.HUBSPOT_PORTAL_ID_PROD }}
              authType: personalaccesskey
              personalAccessKey: ${{ secrets.HUBSPOT_ACCESS_KEY_PROD }}
          EOF

      - name: Deploy to Production
        run: hs cms upload src/my-theme @my-theme --portal=prod --overwrite

      - name: Notify on success
        if: success()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "🚀 本番デプロイ完了！\ncommit: ${{ github.event.head_commit.message }}\nby: ${{ github.actor }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

      - name: Notify on failure
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "❌ 本番デプロイ失敗！確認が必要です。\n${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

HubSpot Developer MCP Server — AIエージェントで開発を加速する

2026年2月19日、HubSpot Developer MCP Server が正式GA（一般公開）されました。 MCP（Model Context Protocol）は、AIツールが外部サービスと連携するための標準規格です。 HubSpot の Developer MCP Server をローカルにインストールすることで、 VS Code・Claude Code・Cursor などのAIエディタが HubSpot の開発者ドキュメントを参照しながら、自然言語でCMSアセットの生成・デプロイ・デバッグを実行できるようになります。

セットアップ手順

# 前提：CLI v8.0.0以上がインストール済みであること
$ hs --version
8.x.x

# MCP Server をセットアップ（対話形式）
$ hs mcp setup

# ↓ 対話式で接続するMCPクライアントを選択
? Which clients would you like to add the MCP server to?
  ❯ ◉ VS Code
    ◉ Claude Code
    ◯ Cursor
    ◯ OpenAI Codex
(Use arrow keys and spacebar to select, Enter to proceed)

✔ HubSpotDev MCP server has been added to: VS Code, Claude Code
Restart your client to apply the changes.

MCPサーバーでできること

デプロイワークフローのベストプラクティス

デプロイ前チェックリスト

ロールバック手順

HubSpotのデザインマネージャーにはバージョン履歴機能があり、 各ファイルの変更履歴から過去のバージョンに戻せます。 ただし、CLIによる一括アップロードではすべてのファイルが上書きされるため、 「Gitタグ + hs cms upload」によるバージョン管理が安全なロールバック手段になります。

# === 本番デプロイ時は必ずGitタグを打つ ===
$ git tag v1.2.0 -m "ヒーローバナーリニューアル"
$ git push origin v1.2.0

# === デプロイ後に問題が発覚した場合のロールバック ===

# ① ロールバックしたいバージョンのタグをチェックアウト
$ git checkout v1.1.0
HEAD is now at abc1234 v1.1.0

# ② 旧バージョンのファイルを本番にアップロード
$ hs upload src/my-theme @my-theme --portal=prod --overwrite
✔ Rollback complete: v1.1.0 deployed to production

# ③ 作業ブランチに戻る
$ git checkout main

# ④ 問題のある変更を修正してから再デプロイ

大規模変更時のデプロイ戦略

• テンプレートの大規模変更： 新しいテンプレートファイルを別名で作成・テストし、問題がなければ旧テンプレートを差し替える。 いきなり既存テンプレートを上書きしない。
• グローバルパーシャル（ヘッダー・フッター）の変更： 全ページに影響するため、変更後は代表的なページを5〜10ページ確認する。 SPとPCの両方でスクロールしながら崩れがないか目視確認する。
• CSS変数の変更（theme.json）： カラー変更は意図していないページで意図しない見え方になる場合がある。 変更前にスクリーンショットを取っておき、変更後と比較する。
• フォームモジュールの変更： フォームが送信できるか・リダイレクトが正常か・CRMにデータが届いているかを必ずテストする。

チーム開発のベストプラクティス

ディレクトリ構成のドキュメント化

# my-company-hubspot

## 前提条件
- Node.js 20以上（CLI v8.0.0以降必須）
- @hubspot/cli グローバルインストール
- 開発ポータルへのアクセス権（ポータルIDは別途共有）

## セットアップ手順

### 1. リポジトリをクローン
git clone https://github.com/mycompany/hubspot-theme.git
cd hubspot-theme

### 2. HubSpot CLIの認証設定
hs init
# 開発ポータルID: 12345678 (別途Slackで共有)
# Personal Access Key: HubSpot管理画面から各自で発行
# https://app.hubspot.com/personal-access-key/12345678

### 3. 必要なスコープ（Personal Access Keyの発行時に選択）
# ✅ CMS - Design Manager
# ✅ Content

### 4. 開発開始
npm run dev
# ブラウザで開発ポータルを開き、編集内容を確認
# https://app.hubspot.com/website-pages/12345678

## ブランチ戦略
# feature/xxx → develop（DEVポータルに自動デプロイ）
# develop → main（本番ポータルに自動デプロイ）

Personal Access Key に必要なスコープ

よくある競合問題と解決策

コードレビューのポイント

• fields.json のデフォルト値： すべてのフィールドに意味のあるデフォルト値が設定されているか。 空文字のままは避ける。
• 存在チェックの漏れ： 画像フィールドは .src、リンクフィールドは .url で存在チェックしているか。
• get_asset_url() の使用： CSS・JS・画像のパス参照が get_asset_url() を通しているか。
• loading 属性： LCP要素には loading="eager"、その他には loading="lazy" が付いているか。
• アクセシビリティ： img タグに alt 属性があるか。インタラクティブ要素に適切な ARIA 属性があるか。
• 標準フッターの存在： すべてのテンプレートに {{ standard_footer_includes }} が含まれているか。

Personal Access Key の期限管理

Personal Access Key には有効期限はありませんが、 セキュリティ上、6ヶ月〜1年ごとに定期ローテーションを推奨します。 チームメンバーが退職した場合は即時無効化してください。 GitHub Secrets の更新も忘れずに行います。