GitHub Actions から Square Cloud へデプロイ

push、リリース、手動実行のたびに、公式 Action がランナーに Square Cloud CLI をインストールして検証し、コードをアプリケーションに送信します。

GitHub Marketplace で見る3 ステップで設定
Linux、Windows、macOS のランナーで、x64 と arm64 に対応。ソースコードは GitHub で公開しています。

3 ステップで push のたびにデプロイ

リポジトリに保存する 2 つの値と、ワークフローファイル 1 つだけ。以降は main への push のたびに、コードがアプリケーションに送信され、再起動されます。

  1. 1

    API キーをシークレットに保存

    アカウントのセキュリティ設定で API キーを作成し、リポジトリのシークレット SQUARECLOUD_API_KEY として保存します。

  2. 2

    アプリケーション ID を保存

    ダッシュボードのアプリケーションページから ID をコピーし、リポジトリ変数 SQUARECLOUD_APP_ID として保存します。

  3. 3

    ワークフローを追加

    下のファイルを .github/workflows/deploy.yml としてコミットします。次に main へ push すると、アプリケーションがデプロイされます。

.github/workflows/deploy.yml
name: Deployon:  push:    branches: [main]jobs:  deploy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          command: commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

  • checkout ステップは残す

    actions/checkout がないと、ランナーには送信するファイルがありません。

  • 停止中でも起動します

    --restart はアップロード後にアプリケーションを再起動し、停止していた場合は起動します。付けない場合、新しいファイルは次の再起動で反映されます。

  • ID はフォルダに置ける

    ID を省略すると、commit はフォルダ内に squarecloud.app があればその ID= 行を読み取るため、commit --restart だけで済みます。

ランナー上で Action が行うこと

すべてのランナーで、この順番で 4 つの処理を行います。どれかが失敗するとワークフローのステップも失敗するため、行われなかったデプロイが緑で表示されることはありません。

  1. 1

    ランナーに合うビルドを取得

    ランナーの OS とプロセッサに合った CLI のリリースを選びます。最新版か、指定したバージョンです。セルフホストランナーではツールキャッシュに保持されます。

  2. 2

    インストール前に検証

    ダウンロードしたファイルの SHA-256 をリリースの checksums.txt と照合します。一致しないファイルがインストールされたり起動されたりすることはありません。

  3. 3

    キーを保存せずに渡す

    キーはログでマスクされ、ジョブの残りの間 SQUARECLOUD_API_KEY として設定されます。ランナーのディスクには何も書き込みません。

  4. 4

    コマンドを実行

    workdir で squarecloud に続けて command を実行します。コマンドが失敗すると、ステップも失敗します。

リリース方法に合わせたワークフロー

Action のドキュメントにある 4 つのパターンを、そのままコピーできます。ハイライトされた行が、上のワークフローから変わる部分です。

  • ステージングと本番

    main への push は本番に、develop への push はステージングに、それぞれ別のアプリケーションへ送られます。

    • Actions タブの Run workflow ボタンで、選んだブランチをデプロイできます
    • concurrency により、同じブランチのデプロイは重ならず順番を待ちます
    .github/workflows/deploy.yml
    name: Deployon:  push:    branches: [main, develop]  workflow_dispatch:concurrency:  group: deploy-${{ github.ref_name }}jobs:  deploy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          command: commit ${{ github.ref_name == 'main' && vars.PRODUCTION_APP_ID || vars.STAGING_APP_ID }} --restart

  • 1 つのリポジトリに複数のアプリケーション

    フォルダごとに独立したアプリケーションです。マトリックスがフォルダごとに 1 つのジョブを作り、並べてデプロイします。

    • workdir で各デプロイの対象フォルダを指定します
    • fail-fast: false により、1 つのデプロイが失敗してもほかは取り消されません
    .github/workflows/deploy.yml
    name: Deployon:  push:    branches: [main]jobs:  deploy:    runs-on: ubuntu-latest    strategy:      fail-fast: false      matrix:        include:          - folder: bot            app: ${{ vars.BOT_APP_ID }}          - folder: website            app: ${{ vars.WEBSITE_APP_ID }}    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          workdir: ${{ matrix.folder }}          command: commit ${{ matrix.app }} --restart

  • リリースの公開時にデプロイ

    公開されたリリースのコードだけがアプリケーションに届きます。

    • push や下書きのリリースではデプロイされません
    .github/workflows/deploy.yml
    name: Deployon:  release:    types: [published]jobs:  deploy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          command: commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

  • シークレットから環境変数を設定

    トークンやパスワードは GitHub のシークレットに保管し、デプロイのたびにアプリケーションへ送信します。env set は指定した変数だけを追加・更新し、commit 後の再起動で読み込まれます。

    • CLI 3.1.1 以降では、スペースや $、&、;、| などの文字を含む値も、シークレットに保存したとおりに届きます
    • CLI 3.1.0 では、各値を自分でシングルクォートで囲んでください
    • シークレットを env 経由で渡すと、その値は GitHub が実行するスクリプトに含まれません
    jobs.deploy.steps
    - uses: squarecloudofc/github-action@v2  with:    token: ${{ secrets.SQUARECLOUD_API_KEY }}    install-only: true- name: Update environment variables  run: squarecloud app env set --app "$APP_ID" "DISCORD_TOKEN=$DISCORD_TOKEN" "DATABASE_URL=$DATABASE_URL"  env:    APP_ID: ${{ vars.SQUARECLOUD_APP_ID }}    DISCORD_TOKEN: ${{ secrets.DISCORD_TOKEN }}    DATABASE_URL: ${{ secrets.DATABASE_URL }}- run: squarecloud commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

5 つの入力

必須なのは token だけです。ほかはデフォルト値のままで使えます。

token必須
Square Cloud の API キー。ワークフローファイルには書かず、シークレットに保管してください。
command
実行する CLI コマンド。squarecloud は付けずに、commit --restart のように書きます。省略すると、Action は CLI のインストールだけを行います。
versionデフォルト latest
インストールする CLI のバージョン。latest または 3.1.0 以降です。最新バージョンの確認に GitHub API を使わないため、そのレート制限に引っかかることはありません。
workdirデフォルト .
コマンドを実行するフォルダ。リポジトリのルートからの相対パスです。
install-onlyデフォルト false
CLI のインストールとキーの設定だけを行い、ジョブの後続ステップで squarecloud を直接使えるようにします。

  • CLI のバージョンを固定

    最新リリースに関係なく、bot フォルダを毎回 CLI 3.1.1 でデプロイします。

    jobs.deploy.steps
    - uses: squarecloudofc/github-action@v2  with:    token: ${{ secrets.SQUARECLOUD_API_KEY }}    version: 3.1.1    workdir: bot    command: commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

  • 複数のコマンドを実行

    install-only を使うと、CLI とキーが後続のステップでも使えます。ビルド、デプロイ、最後に JSON でステータスを取得します。

    jobs.deploy.steps
    - uses: squarecloudofc/github-action@v2  with:    token: ${{ secrets.SQUARECLOUD_API_KEY }}    install-only: true- run: npm ci && npm run build- run: squarecloud commit ${{ vars.SQUARECLOUD_APP_ID }} --restart- run: squarecloud app status ${{ vars.SQUARECLOUD_APP_ID }} --json

どの GitHub ランナーでも

Action は GitHub の Linux、Windows、macOS ランナーで、x64 と arm64 の両方でテストされています。ランナーのバージョンが node24 の Action に対応していれば、セルフホストランナーでも動作します。

  • Linux

    GitHub ホステッドランナーでは x64 と arm64。セルフホストランナーでは x86 や ARMv7 も使えます。

    • ubuntu-latest と ubuntu-24.04-arm でテスト済み

  • Windows

    GitHub ホステッドランナーでは x64 と arm64。セルフホストランナーでは x86 も使えます。

    • windows-latest と windows-11-arm でテスト済み

  • macOS

    Intel と Apple シリコンの両方に、GitHub ホステッドランナーでもセルフホストランナーでも対応します。

    • macos-latest でテスト済み

キーは秘密のまま

Action は API キーを、パスワードと同じように扱います。

  • ログではマスク

    何かが動き出す前にキーをシークレットとして登録するため、どのログ行でも *** と表示されます。

  • ディスクに保存しない

    CLI は SQUARECLOUD_API_KEY からキーを読み取ります。ランナーに保存されることも、コマンドラインで渡されることもありません。

  • 1 つのジョブに限定

    同じジョブの後続ステップは使えますが、ほかのジョブからは使えません。信頼できない Action は別のジョブで動かしてください。

  • リポジトリごとにキー

    リポジトリごとに別のキーを使えば、ほかに影響を与えずに 1 つだけ無効化できます。

ワークフローのための CLI

Action が実行するコマンドはすべて Square Cloud CLI のコマンドで、CLI はターミナルなしでも動くように作られています。

  • -y で確認を省略

    データを変更・削除するコマンドは確認を求めます。ワークフローは応答できないので -y を付けてください。付けないと、コマンドは何も変更せずに終了コード 1 で終わります。

  • スクリプト向けの JSON

    データを出力するコマンドは --json に対応しており、次のステップで解析できる出力が得られます。

  • リクエストを追跡

    ステップの env に SQUARECLOUD_DEBUG: 1 を設定すると、各 API リクエストのメソッド、パス、ステータス、所要時間を記録します。ヘッダーや本文は記録しません。

  • 送信する内容を選ぶ

    commit は squarecloud.ignore に gitignore の構文で書かれたものを除外します。node_modules、.git、ロックファイルは、! で戻さない限り除外されます。

すでに @v2 を使っていますか？

@v2 は新しいバージョンを指すようになったため、ワークフローは変更なしで動き続けます。変更点は次のとおりです。

  • workdir が適用されるようになりました。2.1.2 までは無視され、コマンドはリポジトリのルートで動いていました。
  • キーはコマンドラインで渡されなくなり、ランナーにも保存されません。
  • Windows、macOS、arm64 のランナーに対応しました。
  • CLI のダウンロードはチェックサムで検証され、新しい version 入力でバージョンを固定できます。
  • 最新の CLI の確認に GitHub API を使わなくなったため、API のレート制限の影響を受けません。
  • Action は Node 24 で動作します。

CLI 3.1 ではロックファイルもアップロードから除外されます。引き続き送信するには、squarecloud.ignore に !package-lock.json（またはお使いのロックファイル）を追加してください。

関連リソース

プロジェクトのあらゆる段階に対応するプラン

小さく始めて、必要なときにスケール。縛り契約はありません。

すべてのプランを比較

5点中4.9点 · Google + Trustpilotで402件のレビューTrustpilot

認証を取得したパートナーデータセンターでホスティング
Tier 3ISO 27001SOC 2 Type II常時稼働のDDoS保護
インフラストラクチャを見る

プロジェクトをスケールさせる準備はできましたか？

Square Cloud でプロジェクトをホスティングしてきた 50 万人以上の開発者の仲間入りをしましょう。

今すぐSquare Cloudを始めるプランと料金を見る
  • 予測可能な料金
  • 請求のサプライズなし
  • 数秒でデプロイ
  • 高可用性
  • 安定したスケール
  • 自動再起動
  • SSLとセキュリティを標準搭載
  • 分離されたコンテナ