【GitとFTPの自動連携】Cursor×GitHub ActionsでXserverへFTP自動デプロイ環境

1.FTP自動デプロイ

毎日Cursorで開発していると、避けて通れないのが「本番サーバーへのデプロイ作業」です。Cursorのターミナルから GitHub にプッシュしたあと、わざわざ WinSCP を立ち上げて、XAMPPのローカルフォルダから修正したファイルを目視で探して、Xserverの本番ディレクトリにドラッグ&ドロップしてアップロードする…。毎日のこととなると、これが本当にストレスで、しかも転送漏れや上書きミスでサイトが壊れる事故もしょっちゅう起こしていました。

「コードを書いて git push を叩くだけで、あとは勝手に本番に反映されてくれたら、どれだけ楽だろう」とずっと思っていたところ、AIと格闘しながらリサーチを重ねるうちに、GitHub Actions という仕組みにたどり着きました。今回はその構築手順を、同じように手作業デプロイで疲弊している方に向けて解説します。

GitHub Actions を使って、push するだけで自動デプロイされる仕組みを作る。
FTPのパスワードは GitHub Secrets に暗号化して安全に保管する。
差分転送の設定を入れて、変更のあったファイルだけを高速に送る。

手順1.Xserver側でFTP接続情報を確認する

まずは、GitHubの仮想サーバーがXserverにアクセスするための「鍵」となる接続情報を準備します。Xserverのサーバーパネルにログインし、「サブFTPアカウント設定」または「FTPソフトの設定」から、以下の3点を控えておきます。

項目	内容
FTPホスト名	例 sv****.xserver.jp
FTPユーザー名	例 xs*******
FTPパスワード	FTP接続用に設定したパスワード

普段FTPクライアントで使っている情報と全く同じです。新しく取得し直す必要はありません。

手順2.GitHub SecretsにFTP情報を登録する

次に、控えた接続情報をGitHubに登録します。ここで絶対にやってはいけないのが、FTPパスワードを設定ファイル（deploy.yml）の中に直接書き込むことです。GitHubのリポジトリは公開・非公開にかかわらず、設定ファイルにパスワードを書くと流出のリスクが一気に高まります。必ず「Secrets」という暗号化保管庫を使います。

1. リポジトリ画面 → 上部の Settings タブをクリック
2. 左メニューの Secrets and variables → Actions を選択
3. New repository secret ボタンから、以下の3つを1つずつ登録

Name（変数名）	Secret（値）
FTP_SERVER	手順1のホスト名
FTP_USERNAME	手順1のユーザー名
FTP_PASSWORD	手順1のパスワード

変数名は大文字・小文字を含めて1文字でも違うと動きません。コピペで正確に入れてください。

手順3.ワークフローファイル(deploy.yml)を作成する

Cursor でプロジェクトを開き、ルートディレクトリに .github/workflows/deploy.yml というフォルダとファイルを作成し、以下を貼り付けます。

name: Deploy to Xserver

on:
  push:
    branches:
      - main # mainブランチにプッシュされた時のみ実行

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # ★差分転送に必須

      - name: FTP Deploy
        uses: SamKirkland/FTP-Deploy-Action@v4.3.5
        with:
          server: ${{ secrets.FTP_SERVER }}
          username: ${{ secrets.FTP_USERNAME }}
          password: ${{ secrets.FTP_PASSWORD }}
          local-dir: ./
          server-dir: /ドメイン名/public_html/ # ★末尾のスラッシュ必須
          exclude: |
            **/.git*
            **/.git*/**
            **/.github*
            **/.github*/**

これが「mainブランチに変更があったら、Secretsに保管した鍵を使って、Xserverの指定ディレクトリに変更分だけを転送せよ」というGitHubへの指示書になります。

手順4.Cursorからプッシュして動作確認

設定ファイルができたら、Cursor のターミナルからコミットしてプッシュします。

git add .
git commit -m "自動デプロイ用のGitHub Actions設定を追加"
git push origin main

プッシュ後、ブラウザでGitHubリポジトリの Actions タブを開きます。黄色のインジケーターが回り出し、自動化が走っていることが確認できます。数十秒後に緑のチェックマーク（✅）が出れば成功です。あとはXserverにアクセスして、ファイルが反映されているかを確認してみてください。

2.はまりやすい3つの落とし穴

シンプルな設定に見えますが、最初に必ずと言っていいほど初心者がつまずく3つのワナがあります。エラーが出たら、まずはここを疑ってください。

ワナ1.server-dir の末尾スラッシュ忘れ

server-dir: /ドメイン名/public_html/ の末尾にあるスラッシュ（/）を書き忘れると、確実にエラーになります。スラッシュがないと、プログラムはそれを「ディレクトリ」ではなく「ファイル名」として認識してしまい、「指定されたディレクトリが存在しない」と怒られます。最も頻発するミスです。

ワナ2.fetch-depth: 0 の書き忘れによる「毎回全ファイル転送」

actions/checkout@v4 の下の fetch-depth: 0 は、「Gitの過去の変更履歴をすべて取得する」という指示です。これを書き忘れると、プログラムは最新の状態しか見られず、前回との差分計算ができません。結果として、ファイルを1つ修正しただけでも全ファイルを毎回上書き転送してしまい、デプロイに膨大な時間がかかるようになります。

ワナ3..ftp-deploy-sync-state.json を消さない

自動デプロイが一度成功すると、Xserverの本番ディレクトリに .ftp-deploy-sync-state.json という見慣れないファイルが生成されます。これは「前回どのファイルを送ったか」を記録するための重要なファイルです。本番サーバーを整理しようとして誤って削除すると、状態がリセットされて次回のデプロイ時に全ファイルの再転送が発生します。絶対に触らず、そのまま残しておいてください。

3.便利な工夫

毎回 git push origin main と打つのも、慣れてくるとさらに省略したくなります。Cursorのソース管理パネル（左サイドバーのGitアイコン）を使えば、コミットメッセージを書いて「Commit & Push」ボタンを押すだけでプッシュが完了します。ターミナルにすら触れずにデプロイが完結するので、よりコーディングに集中できるようになります。

また、本番反映前に動作確認をしたい場合は、main ブランチではなく develop ブランチを別途作って、develop プッシュ時はステージング環境（テスト用ディレクトリ）に転送する、という二段構えにする方法もあります。deploy.yml を複製して branches: と server-dir: を変えるだけで実現できます。

4.備考

1.そもそもGitHub Actionsとは

GitHub が公式に提供しているCI/CD（継続的インテグレーション／継続的デプロイメント）プラットフォームです。難しく聞こえますが、要するに「GitHub上で特定のイベント（今回でいえば main ブランチへのプッシュ）が起きたら、あらかじめ決めておいた作業を自動で実行してくれる仕組み」のことです。

今回の流れを噛み砕くとこうなります。

Cursor から git push を実行する（トリガー）
プッシュを検知したGitHubが、クラウド上に一時的な仮想サーバー（Ubuntu）を立ち上げる
その仮想サーバーが、最新コードと過去コードを比較して変更分のファイルだけを抽出する
抽出したファイルを Xserver に FTP 転送する

この一連の処理はすべてGitHub側のサーバーで実行されるため、自分のPCの電源を切ってしまっても問題なく完結します。これが本当にありがたい。

2.YAML（ヤムル：.yml / .yaml）とは

今回 deploy.yml として作成した、自動化の指示書のファイル形式です。設定ファイルとして広く普及しています。

重要な注意点として、YAMLは行頭の空白（インデント）でデータの親子関係を判断します。スペースの数がズレていたり、スペースの代わりにTabキーを使ったりすると、構造が壊れてエラーになります。エラーが出たら、まずインデントを疑うのが鉄則です。

参考リンク：GitHub Actions のワークフロー構文（GitHub Docs）

3..ftp-deploy-sync-state.json の正体

FTP-Deploy-Action が本番サーバー側にひっそりと残す、状態保存用のJSONファイルです。次回デプロイ時に、プログラムはこのファイルの中身と最新コードを比較して、変更のあったファイルだけを特定します。この仕組みのおかげで、何百ファイルあるプロジェクトでも、変更分だけの数秒〜十数秒で転送が完了します。

参考リンク：FTP-Deploy-Action 公式リポジトリ（GitHub）

4.今回の設定にかかる時間と得られるもの

GitHubアカウントとXserverの環境が整っていれば、設定作業はおおよそ30分〜1時間程度です。最初はYAMLやSecretsなど見慣れないものに戸惑うかもしれませんが、この30分の投資で得られる対価は計り知れません。

「FTPソフトを立ち上げて、フォルダ階層を潜って、修正したファイルを目視で探してドラッグ&ドロップする」という、これから先何百回と発生するはずだった手作業の時間が、今後の人生から完全に消えます。Cursor で書いて git push を叩くだけで本番が更新される体験は、一度味わうと、もう手作業のデプロイには戻れなくなります。