通过 GitHub Actions 部署到 Square Cloud
每次推送、发布发行版或手动运行时，官方 Action 都会在运行器上安装 Square Cloud CLI、完成校验，并把你的代码发送到你的应用。
三步实现每次推送自动部署
只需在仓库中保存两个值，再添加一个工作流文件。之后每次推送到 main，代码都会发送到你的应用并重启它。
- 1
将 API 密钥存为机密
在账户的安全设置中创建 API 密钥，并在仓库中将其保存为机密 SQUARECLOUD_API_KEY。
- 2
保存应用 ID
从控制台的应用页面复制 ID，并将其保存为仓库变量 SQUARECLOUD_APP_ID。
- 3
添加工作流
将下面的文件提交为 .github/workflows/deploy.yml。下次推送到 main 时就会部署你的应用。
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 在运行器上做了什么
在每个运行器上按此顺序完成四个步骤。任何一步失败，工作流步骤也会失败，所以没有真正完成的部署绝不会显示为绿色。
- 1
下载适合运行器的构建
根据运行器的系统和处理器选择 CLI 发行版：最新版，或你固定的版本。自建运行器会将其保存在工具缓存中。
- 2
安装前先校验
下载文件的 SHA-256 会与发行版的
checksums.txt比对。不匹配的文件绝不会被安装或运行。 - 3
传递密钥但不保存
密钥会在日志中被屏蔽，并在作业的剩余步骤中设置为
SQUARECLOUD_API_KEY。不会向运行器的磁盘写入任何内容。 - 4
运行你的命令
squarecloud加上你的command会在workdir中运行。命令失败时，该步骤也会失败。
适合各种发布方式的工作流
四种来自 Action 文档的模式，可直接复制。高亮的行就是相对上面工作流的改动。
预发布与生产环境
推送到
main会部署到生产环境，推送到develop会部署到预发布环境，各自对应独立的应用。- Actions 标签页中的 Run workflow 按钮可以部署你选择的分支
concurrency让同一分支的部署依次等待，而不是相互重叠
.github/workflows/deploy.ymlname: 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一个仓库中的多个应用
每个文件夹都是独立的应用。矩阵会并行部署它们，每个文件夹一个作业。
workdir将每次部署指向对应的文件夹fail-fast: false让一次部署失败时不会取消其他部署
.github/workflows/deploy.ymlname: 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发布发行版时部署
只有已发布发行版的代码才会到达应用。
- 推送和草稿发行版不会触发部署
.github/workflows/deploy.ymlname: 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- 从 CLI 3.1.1 起，包含空格或
五个输入
只有 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 版本
无论最新发行版是哪个，每次都用 CLI 3.1.1 部署 bot 文件夹。
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 读取密钥。它不会保存在运行器上，也不会通过命令行传递。
仅限一个作业
同一作业的后续步骤可以使用它，其他作业不能。请在单独的作业中运行你不信任的 Action。
每个仓库一个密钥
为每个仓库使用单独的密钥，这样撤销其中一个时不会影响其他仓库。
为工作流打造的 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 还会在上传时排除锁文件。如果要继续发送你的锁文件，请将 !package-lock.json（或你的锁文件）添加到 squarecloud.ignore。
项目每个阶段都有合适的套餐
从小规模开始，按需扩展，无绑定合约。
4.9 分（满分 5 分）· Google + Trustpilot 上的 402 条评价Trustpilot