GitHub Actions 常用 CLI 命令详解

详解 GitHub Actions 相关 CLI 命令，覆盖 GitHub CLI gh（workflow run/list/view/disable/enable、run list/view/watch/cancel/rerun/delete/download、cache）、act 本地运行工作流（list/run/dryrun/graph/输入），并给出真实命令回显

GitHub ActionsGitHub ActionsDevOpsCICD2026/10/10

GitHub Actions 常用 CLI 命令详解

目标：系统讲解 GitHub Actions 的常用命令行工具：官方 GitHub CLI gh（含 workflow、run、cache 等子命令系列）与本地运行工作流的 act，逐条给出真实命令与回显。本文已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS
  • GitHub CLI gh：2.102.0
  • act（本地运行 GitHub Actions 工作流）：0.2.89
  • 示例仓库：/opt/data/github-actions/myapp（远程指向 quzuo-ops/demo-app）
  • 若使用真实 GitHub 仓库，需先用 gh auth login（见"七、认证"）

二、工具概览

工具版本作用
gh2.102.0官方 CLI，管理 workflow、run、cache、artifact 等
act0.2.89本地实时执行 GitHub Actions 工作流，不依赖 GitHub 云端

两者互补：gh 面向云端 Actions 的查看与触发；act 面向本地开发快速校验工作流。

三、前置条件

  • gh：需安装并授权（gh auth login）；对目标仓库有相应权限
  • act：需在安装目录内可用，且本机 Docker 守护进程运行正常
  • 工作流文件位于仓库 .github/workflows/

安装方式（apt / 官方二进制）

# 安装 gh（GitHub CLI）
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg -o /usr/share/keyrings/githubcli.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/githubcli.gpg] https://cli.github.com/packages stable main" > /etc/apt/sources.list.d/github-cli.list
apt-get update && apt-get install -y gh

# 安装 act（下载官方二进制到 /usr/local/bin）
curl -fsSL -o /tmp/act.tar.gz "https://github.com/nektos/act/releases/latest/download/act_Linux_x86_64.tar.gz"
tar xzf /tmp/act.tar.gz -C /usr/local/bin act && chmod +x /usr/local/bin/act

安装后版本校验回显：

gh version 2.102.0 (2026-09-30)

act version 0.2.89

四、gh 命令详解

4.1 gh workflow 系列（工作流视图与触发）

gh workflow list——列出仓库工作流：

USAGE
  gh workflow list [flags]

ALIASES
  gh workflow ls

FLAGS
  -a, --all               Include disabled workflows
  -L, --limit int         Maximum number of workflows to fetch (default 50)
  -q, --jq expression     Filter JSON output using a jq expression

gh workflow list -R quzuo-ops/demo-app

gh workflow run——以 dispatch 事件手动触发工作流：

USAGE
  gh workflow run [<workflow-id> | <workflow-name>] [flags]

FLAGS
  -F, --field key=value       Add a string parameter in key=value format
  -f, --raw-field key=value   Add a string parameter in key=value format
  -r, --ref string            Branch or tag name which contains the version of the workflow file
      --json                  Read workflow inputs as JSON via STDIN

gh workflow run ci.yml -R quzuo-ops/demo-app --ref main
gh workflow run deploy.yml -f target=prod -f version=1.2.3    # 带手动输入
echo '{"target":"prod","version":"1.2.3"}' | gh workflow run deploy.yml --json

gh workflow view——查看工作流概况或 YAML：

USAGE
  gh workflow view [<workflow-id> | <workflow-name> | <filename>] [flags]

FLAGS
  -r, --ref string   The branch or tag name
  -w, --web          Open workflow in the browser
  -y, --yaml         View the workflow yaml file

gh workflow view ci.yml -y          # 打印工作流 YAML
gh workflow view ci.yml -R quzuo-ops/demo-app

gh workflow enable/disable——启停工作流：

USAGE
  gh workflow disable [<workflow-id> | <workflow-name>]
  gh workflow enable  [<workflow-id> | <workflow-name>]

gh workflow disable ci.yml -R quzuo-ops/demo-app   # 停用
gh workflow enable  ci.yml -R quzuo-ops/demo-app   # 启用

4.2 gh run 系列（运行实例追踪）

gh run list——列出最近运行：

USAGE
  gh run list [flags]
ALIASES
  gh run ls

FLAGS
  -a, --all               Include disabled workflows
  -b, --branch string     Filter runs by branch
  -L, --limit int         Maximum number of runs to fetch (default 20)
  -s, --status string     Filter runs by status
  -w, --workflow string   Filter runs by workflow

gh run list -R quzuo-ops/demo-app
gh run list -w ci.yml --status success --limit 5

gh run view——查看单次运行详情/日志：

USAGE
  gh run view [<run-id>] [flags]

FLAGS
  -a, --attempt uint      The attempt number of the workflow run
      --exit-status       Exit with non-zero status if run failed
  -j, --job string        View a specific job ID
      --log               View full log for either a run or specific job
      --log-failed        View the log for any failed steps
  -v, --verbose           Show job steps
  -w, --web               Open run in the browser

gh run view 12345 -R quzuo-ops/demo-app          # 查看运行摘要
gh run view 12345 --log --job 456789             # 看某 job 完整日志
gh run view 12345 --log-failed                   # 只看失败步骤
gh run view 12345 --exit-status && echo OK        # 非零退出码判断成败

gh run watch——实时跟踪直到结束：

USAGE
  gh run watch <run-id> [flags]

FLAGS
      --compact        Show only relevant/failed steps
      --exit-status    Exit with non-zero status if run fails
  -i, --interval int   Refresh interval in seconds (default 3)

gh run watch 12345 --compact -i 5

gh run cancel/rerun/delete/download——运行控制与制品下载：

gh run cancel 12345 -R quzuo-ops/demo-app   # 取消
gh run rerun 12345 --failed                 # 只重跑失败 job
gh run rerun 12345 --job 456789 --debug     # 带 debug 重跑指定 job
gh run delete 12345                         # 删除运行记录
gh run download 12345 -n build-artifact     # 下载某制品

💡 说明：gh run rerun --job 需用 gh run view <run-id> --json jobs --jq '.jobs[] | {name, databaseId}' 查到的的 databaseId（网页 URL 里的数字不可直接用，会 404）。

4.3 gh cache 系列（Actions 缓存）

USAGE
  gh cache <command> [flags]
AVAILABLE COMMANDS
  delete:        Delete GitHub Actions caches
  list:          List GitHub Actions caches

gh cache list -R quzuo-ops/demo-app
gh cache delete 582 --R quzuo-ops/demo-app    # 删除指定缓存

五、act 命令详解（本地运行工作流）

5.1 基本视图：act list 与真实回显

cd /opt/data/github-actions/myapp
act list -W .github/workflows

实测回显：

Stage  Job ID  Job name  Workflow name  Workflow file  Events
0      build   build     CI             ci.yml         push

5.2 运行整个工作流

act push -W .github/workflows

实测回显（节选，job 各步骤逐步回放）：

[CI/build] ⭐ Run Set up job
[CI/build] 🚀  Start image=node:20-bookworm-slim
[CI/build]   ✅  Success - Set up job
[CI/build] ⭐ Run Main Checkout 代码
[CI/build]   ✅  Success - Main Checkout 代码 [25.273241ms]
[CI/build] ⭐ Run Main 打印工作区
[CI/build]   | 仓库名: quzuo-ops/demo-app
[CI/build]   ✅  Success - Main 打印工作区 [101.480655ms]
[CI/build] ⭐ Run Main 输出信息
[CI/build]   | Hello GitHub Actions from act
[CI/build] 🏁  Job succeeded

5.3 指定 job 运行

act push -j build -W .github/workflows

（输出同 5.2，仅运行 build 这一个 job。）

5.4 dry-run 校验语法：act -n

act -n -j build -W .github/workflows

实测回显（dry-run，仅做语法预检）：

*DRYRUN* [CI/build] ⭐ Run Set up job
*DRYRUN* [CI/build] 🚀  Start image=node:20-bookworm-slim
*DRYRUN* [CI/build]   ✅  Success - Set up job
*DRYRUN* [CI/build] ⭐ Run Main Checkout 代码
*DRYRUN* [CI/build]   ✅  Success - Main Checkout 代码 [12.940068ms]
*DRYRUN* [CI/build] 🏁  Job succeeded

5.5 图形化依赖：act --graph

act --graph -W .github/workflows

实测回显：

 ╭───────╮
 │ build │
 ╰───────╯

5.6 手动事件与输入：workflow_dispatch / --input

act workflow_dispatch -j deploy --input target=prod

⚠️ 说明：仅当工作流 on 声明了 workflow_dispatch 且 job 接受输入时才可传 --input；否则以 push 事件运行。

5.7 指定运行镜像：-P/--platform

act 默认按 runs-on 拉取对应镜像，可在 actrc 或 -P 覆盖：

act push -j build -P ubuntu-latest=node:20-bookworm-slim -W .github/workflows

六、act 详细参数速查（真实 --help 节选）

Usage:
  act [event name to run] [flags]

      --action-cache-path string   Path where actions get cached (default "/root/.cache/act")
  -a, --actor string                user that triggered the event (default "nektos/act")
  -n, --dryrun                      disable container creation, validates workflow correctness
  -C, --directory string            working directory (default ".")
  -e, --eventpath string            path to event JSON file
  -g, --graph                       draw workflows
      --input stringArray           action input to make available to actions
  -j, --job string                  run a specific job ID
  -l, --list                        list workflows
  -P, --platform stringArray        custom image to use per platform, e.g. -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04
      --privileged                  use privileged mode
  -p, --pull                        pull docker image(s) even if already present (default true)
  -q, --quiet                       disable logging of output from steps
      --rebuild                     rebuild local action docker image(s) even if already present (default true)
  -W, --workflows string            path to workflow file(s)"

七、认证（gh auth login）

gh auth login

实测回显/状态（未登录时）：

You are not logged into any GitHub hosts. To log in, run: gh auth login

gh auth status -t

⚠️ 说明：交互式 gh auth login 会引导选 GitHub.com、HTTPS/SSH 与鉴权方式；无头环境可用 GH_TOKEN=ghp_xxxx gh ... 或 git pipeline 的 echo $GH_TOKEN | gh auth login --with-token。由于本机未持有真实仓库令牌，上述 gh workflow/run 命令的真实鉴权回显以读者在授权仓库上的输出为准。

八、注意事项

  • act 需要一个本地隔离运行环境来执行工作流 job。实测若出现 overlay 挂载 invalid argument 的报错，可将该运行环境的存储驱动改为 vfs（在守护进程配置文件的 "storage-driver":"vfs"），重启后即可正常运行 act。
  • act 的 github.repository 依 git 远程地址推导；--actor 默认 nektos/act。
  • gh run rerun --job 必须用 databaseId 而非 URL 里的进度数字。
  • secrets 务必经 env: 注入后在命令内引用，避免回显到日志。

九、常见问题

Q1：act 报 Could not find any stages to run？

-W 应指向含工作流的目录（如 .github/workflows），并配合 -j <job> 指定 job。

Q2：act 提示拉取运行镜像失败/镜像解析失败？

本机到镜像中心网络受限时，在运行时配置文件里配置 registry 镜像加速（如 https://docker.m.daocloud.io、https://docker.1ms.run）并重启守护进程；storage 驱动冲突时改 vfs。

Q3：gh 提示未登录？

先 gh auth login，或设置 GH_TOKEN 环境变量。

Q4：如何看某次运行失败的确切步骤？

gh run view <run-id> --log-failed 只看失败步骤；act 本地则 act -j <job> 直接重现。

十、参考链接