github

使用 orbit CLI 管理 GitHub

通过 orbit CLI 管理 GitHub 仓库、拉取请求、议题、发布、分支、标签、提交、工作流运行、密钥和用户。通过 REST API 同时支持 GitHub.com 和 GitHub Enterprise，并支持多个配置文件和 1Password 密钥解析。

前提条件

1. 已安装 orbit CLI — 如果 which orbit 执行失败，请使用以下命令安装：
   • macOS/Linux（Homebrew）： brew install jorgemuza/tap/orbit
   • macOS/Linux（脚本）： curl -sSfL https://raw.githubusercontent.com/jorgemuza/orbit/main/install.sh | sh
   • Windows（Scoop）： scoop bucket add jorgemuza https://github.com/jorgemuza/scoop-bucket && scoop install orbit
2. 已在 ~/.config/orbit/config.yaml 中配置带有 github 服务的配置文件
3. 有效的凭据（个人访问令牌）——可存储为 1Password（op://）或 Infisical（infisical://）引用

快速参考

所有命令遵循以下格式：orbit -p <profile> github <command> [flags]

别名：orbit -p <profile> gh <command> [flags]

所有命令都支持使用 -o json 输出 JSON。有关完整的命令详情和所有标志，请参阅 references/commands.md。

仓库标识

仓库始终使用 owner/repo 格式引用：

• orbit -p myprofile gh repo octocat/hello-world
• orbit -p myprofile gh repo kubernetes/kubernetes

核心工作流

浏览仓库

# View repo details
orbit -p myprofile gh repo octocat/hello-world

# List your repos (sorted by most recently pushed)
orbit -p myprofile gh repos

# List repos in an organization
orbit -p myprofile gh repos --org kubernetes

# List repos with limit
orbit -p myprofile gh repos --limit 10

# Edit repo settings
orbit -p myprofile gh repo edit Paybook/ai --description "Updated"

# Archive a repo
orbit -p myprofile gh repo edit Paybook/ai --archived

# List collaborators
orbit -p myprofile gh repo collab list Paybook/ai

# Add collaborator
orbit -p myprofile gh repo collab add Paybook/ai jorgemuza --permission admin

# Remove collaborator
orbit -p myprofile gh repo collab remove Paybook/ai jorgemuza

处理拉取请求

# List open PRs
orbit -p myprofile gh pr list octocat/hello-world

# List closed PRs
orbit -p myprofile gh pr list octocat/hello-world --state closed

# View PR details (shows head/base branch, labels, comments)
orbit -p myprofile gh pr view octocat/hello-world 42

# Create a PR
orbit -p myprofile gh pr create octocat/hello-world \
  --head feature/login --base main --title "Add login page"

# Merge a PR (with optional method: merge, squash, rebase)
orbit -p myprofile gh pr merge octocat/hello-world 42 --method squash

# Add a comment
orbit -p myprofile gh pr comment octocat/hello-world 42 --body "LGTM!"

# List comments
orbit -p myprofile gh pr comments octocat/hello-world 42

GitHub Actions 工作流运行

# List recent workflow runs
orbit -p myprofile gh run list octocat/hello-world

# Filter by branch and status
orbit -p myprofile gh run list octocat/hello-world --branch main --status completed

# View workflow run details, including every job and its steps
orbit -p myprofile gh run view octocat/hello-world 12345

# Why did it fail? Print the log output of the failed step(s) only
orbit -p myprofile gh run view octocat/hello-world 12345 --log-failed

# List the jobs of a run (ID, status, conclusion, elapsed, name)
orbit -p myprofile gh run jobs octocat/hello-world 12345

# Full logs: the whole run, or a single job
orbit -p myprofile gh run log octocat/hello-world 12345
orbit -p myprofile gh run log octocat/hello-world 12345 --job 67890
orbit -p myprofile gh run log octocat/hello-world 12345 --failed

# View one job of a run, or a specific attempt
orbit -p myprofile gh run view octocat/hello-world 12345 --job 67890
orbit -p myprofile gh run view octocat/hello-world 12345 --attempt 2

# Non-zero exit when the run did not succeed (for scripts and CI gates)
orbit -p myprofile gh run view octocat/hello-world 12345 --exit-status

# Watch a run in real-time (polls and shows job/step progress until completion)
orbit -p myprofile gh run watch octocat/hello-world
orbit -p myprofile gh run watch octocat/hello-world 12345 --interval 10

# Cancel a running workflow
orbit -p myprofile gh run cancel octocat/hello-world 12345

# Re-run a workflow
orbit -p myprofile gh run rerun octocat/hello-world 12345

运行别名：run、actions — 因此也可以使用 orbit gh actions list octocat/hello-world。

如果未提供 run-id，watch 命令会自动查找最近一次正在进行的运行。它会实时显示作业和步骤状态及已用时间；如果运行失败，则会报错退出。

获取日志（--log、--log-failed、run log）时会跟随 GitHub 重定向到已签名的存储 URL。如果为服务配置了代理、环境代理生效，或者设置了 tls_skip_verify，orbit 会拒绝跟随重定向——因为它无法验证请求最终会发往何处，而替代方案可能会在不提示的情况下获取内部服务。**目前，使用企业代理的用户无法获取日志。**错误信息会指出哪些设置生效以及需要如何更改；其他所有 run 命令均可正常使用，而 run view 会打印运行的 URL，供你在浏览器中查看日志。

要调试失败的运行，请先执行 run view <repo> <run-id>：该命令会列出每个作业和步骤，因此可以立即看到失败的步骤。接着，执行 run view <repo> <run-id> --log-failed，即可通过一条命令打印失败步骤的日志输出；它会聚焦于失败步骤，而不是倾倒整个运行的日志。日志归属判断尽力而为，每个片段都会在 matched_by 中说明其定位方式：step order 表示定位可靠；error marker 表示找到了正确的日志区段，但步骤归属是推断得出的；step order (unconfirmed) 表示没有任何信息佐证匹配结果——显示的日志片段可能并非来自失败步骤。如果某个步骤没有自己的输出，命令会明确说明，而不会借用相邻步骤的输出；如果日志没有覆盖某个步骤，会报告日志被截断；如果无法缩小日志范围，则会打印完整日志并指出失败步骤名称。请参阅日志获取注意事项。--log-failed 也可以与 --job 搭配使用，将范围限定为单个作业；所有日志命令都支持 -o json。

工作流管理

# List workflows (get the numeric workflow ID)
orbit -p myprofile gh workflow list octocat/hello-world

# Trigger a workflow dispatch (--ref is required)
orbit -p myprofile gh workflow run octocat/hello-world 245836153 --ref main

# Trigger with inputs
orbit -p myprofile gh workflow run octocat/hello-world 245836153 --ref main --input env=staging

# Enable/disable a workflow
orbit -p myprofile gh workflow enable octocat/hello-world 245836153
orbit -p myprofile gh workflow disable octocat/hello-world 245836153

重要：workflow run 需要数字形式的工作流 ID（可通过 workflow list 获取），而不是文件名。必须提供 --ref 标志。

GitHub Actions 密钥

# List repository secrets
orbit -p myprofile gh secret list octocat/hello-world

# Create or update a secret
orbit -p myprofile gh secret set octocat/hello-world MY_SECRET "secret-value"

# Delete a secret
orbit -p myprofile gh secret delete octocat/hello-world MY_SECRET

密钥会先在客户端使用仓库的公钥加密，然后再发送到 API。

分支和标签

# List branches
orbit -p myprofile gh branch list octocat/hello-world

# View branch details (includes latest commit)
orbit -p myprofile gh branch view octocat/hello-world main

# List tags
orbit -p myprofile gh tag list octocat/hello-world

提交

# List recent commits (default branch)
orbit -p myprofile gh commit list octocat/hello-world

# List commits on a specific branch
orbit -p myprofile gh commit list octocat/hello-world --ref feature/login

# View commit details
orbit -p myprofile gh commit view octocat/hello-world abc1234

议题

# List open issues
orbit -p myprofile gh issue list octocat/hello-world --state open

# Filter by labels
orbit -p myprofile gh issue list octocat/hello-world --labels bug,urgent

# View issue details
orbit -p myprofile gh issue view octocat/hello-world 1

# Create an issue
orbit -p myprofile gh issue create octocat/hello-world --title "Fix login bug" --labels bug,urgent

# Close an issue
orbit -p myprofile gh issue close octocat/hello-world 1

# Add a comment to an issue
orbit -p myprofile gh issue comment octocat/hello-world 1 --body "Working on this"

发布

# List releases
orbit -p myprofile gh release list octocat/hello-world

# View a specific release
orbit -p myprofile gh release view octocat/hello-world 12345

# View the latest release
orbit -p myprofile gh release latest octocat/hello-world

用户

# Show current authenticated user
orbit -p myprofile gh user me

# View a user profile
orbit -p myprofile gh user view octocat

原始 API 访问

上述命令未涵盖的任何操作，都可以通过 gh api 访问。它使用配置文件的凭据调用任意 GitHub REST 端点。端点是相对于已配置基础 URL 的路径（可省略开头的斜杠），因此在 GitHub Enterprise 上也能直接使用。

# Any GET endpoint, pretty-printed
orbit -p myprofile gh api /repos/cli/cli
orbit -p myprofile gh api /repos/cli/cli/community/profile

# Every page of a collection (GET only)
orbit -p myprofile gh api /repos/cli/cli/issues --paginate -F per_page=100

# Status line and headers, e.g. to read rate limits
orbit -p myprofile gh api /rate_limit -i

# Write requests: the method defaults to POST once fields are supplied
orbit -p myprofile gh api /repos/octocat/hello-world/issues \
  -f title="Bug report" -F [email protected]

# Array fields: repeat key[] to build a JSON array
orbit -p myprofile gh api /repos/octocat/hello-world/issues \
  -f title="Bug report" -F 'labels[]=bug' -F 'labels[]=priority-1'

# Explicit method
orbit -p myprofile gh api /repos/octocat/hello-world/issues/1 -X PATCH -F state=closed

# Hand-written body from a file (or '-' for stdin)
orbit -p myprofile gh api /repos/octocat/hello-world/issues --input payload.json

# Request a specific media type
orbit -p myprofile gh api /repos/cli/cli/pulls/1 -H "Accept: application/vnd.github.diff"

-F 会推断类型（42 → 数字，true/false → 布尔值，null → JSON null，@file → 文件内容）；-f 始终发送字符串。在 GET/HEAD 请求中，字段会成为查询参数，而不是请求体。

两个字段标志都支持 key[]=value 数组形式：重复使用会构建 JSON 数组（-F 'labels[]=bug' -F 'labels[]=p1' → {"labels":["bug","p1"]}），元素按照与标量相同的规则进行类型处理；即使只出现一次，结果仍是数组；只写 key[] 则会发送空数组。

此命令只会与配置文件连接所指向的主机通信。如果完整 URL、分页链接或重定向指向其他主机，命令会拒绝请求，而不会跟随，因为请求会携带令牌。

常见模式

获取供脚本处理的 JSON： 任何命令都支持 -o json，以输出机器可读的数据：

orbit -p myprofile gh pr list octocat/hello-world -o json | jq '.[].title'

检查分支的 CI 状态：

orbit -p myprofile gh run list octocat/hello-world --branch main --limit 1

监控发布流水线：

orbit -p myprofile gh run watch octocat/hello-world

找出 CI 失败的原因：

# Most recent failure on main
orbit -p myprofile gh run list octocat/hello-world --branch main --status failure --limit 1
# Which step failed, and what it printed
orbit -p myprofile gh run view octocat/hello-world 12345 --log-failed

设置部署密钥：

orbit -p myprofile gh secret set octocat/hello-world DEPLOY_TOKEN "ghp_xxxxx"

端到端审查 PR：

# View PR details
orbit -p myprofile gh pr view octocat/hello-world 42
# Check its workflow runs
orbit -p myprofile gh run list octocat/hello-world --branch feature/login --limit 1
# Read discussion
orbit -p myprofile gh pr comments octocat/hello-world 42
# Approve with comment
orbit -p myprofile gh pr comment octocat/hello-world 42 --body "Approved, looks good"

重要说明

• 需要配置文件 — 始终传入 -p <profile>，以选择 GitHub 连接。该配置文件必须配置一个类型为 github 的服务。
• 服务标志 — 如果配置文件中有多个 GitHub 服务，请使用 --service <name> 进行区分。
• 云端与 Enterprise — 两者均可使用。对于 GitHub.com，base_url 默认为 https://api.github.com。对于 GitHub Enterprise，请在配置文件中设置 base_url。
• 密钥引用 - 配置中的凭据可以使用 1Password（op://vault/item/field）或 Infisical（infisical://<env>/<path>/<KEY>）引用，并在运行时解析。运行一次 orbit auth，即可解析并缓存所有密钥（1Password 只需进行一次生物识别提示）。使用 orbit auth clear 清除缓存。请参阅 密钥。
• 分页 - 大多数列表命令默认返回 20-50 条结果。使用 --limit N 调整数量。gh api --paginate 会跟随 Link rel="next" 并获取所有页面，因此请搭配较大的 per_page 使用。
• 原始 API - gh api <endpoint> 可以访问类型化命令未涵盖的任何 REST 端点。它可以写入数据，因此请仔细检查请求方法：提供 -f/-F/--input 时，除非 -X 另有指定，否则请求方法为 POST。