github-integration

GitHub 集成

在 Claude Code 云端和 GitHub Copilot 编码 Agent 环境中启用 gh CLI 访问权限，让 Agent 能够创建 PR、管理问题并与 GitHub API 交互。

何时使用此技能

在以下情况下启用：

• 用户希望云端 AI Agent 使用 gh（PR、问题、发布、API 调用）
• 用户需要在 Claude Code 云端会话中安装 gh
• 用户希望为 GitHub Copilot Agent 添加 copilot-setup-steps.yml
• 在云端会话中，gh 命令因身份验证或“未找到”错误而失败
• 用户希望为任何基于云的 AI 编码 Agent 启用 GitHub 集成

决策树

Which cloud environment?

Claude Code cloud (claude.ai/code)?
  → gh is NOT pre-installed in the default image
  → Install via setup script: apt update && apt install -y gh
  → Set GH_TOKEN as environment variable in environment settings
  → For repo-portable setup, use SessionStart hook instead
  → Use -R owner/repo flag with gh due to sandbox proxy

GitHub Copilot coding agent?
  → Add .github/copilot-setup-steps.yml to the repo
  → gh IS pre-installed; just configure GH_TOKEN
  → Commit and push — agent sessions pick it up automatically

gh commands failing?
  → "command not found" → gh not installed; add to setup script
  → HTTP 401 → GH_TOKEN not set; add to environment variables
  → HTTP 403 → Token lacks required scope; check permissions
  → "could not determine repo" → Use -R owner/repo flag
  → See references/cloud-auth.md for more

Need gh in local dev too?
  → Run: gh auth login (interactive, browser-based)
  → Or set GH_TOKEN env var for headless/CI use

两种环境，两种方法

Claude Code Cloud（claude.ai/code）

Claude Code Cloud 会在由 Anthropic 管理的 VM 中运行会话。系统不会预装 gh CLI。你需要准备两样东西：

1. 设置脚本 — 在会话启动时安装 gh
2. GH_TOKEN 环境变量 — 用 GitHub PAT 对 gh 进行身份验证

快速开始：设置脚本

在 Claude Code 网页界面中：Environment Settings → Setup script：

#!/bin/bash
apt update && apt install -y gh

然后将 GH_TOKEN 添加为环境变量，并填入你的 GitHub Personal Access Token（需要 repo 权限范围）。

替代方案：SessionStart Hook（可在不同仓库间移植）

在仓库的 .claude/settings.json 中添加：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "if [ \"$CLAUDE_CODE_REMOTE\" = \"true\" ]; then apt update && apt install -y gh; fi",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

CLAUDE_CODE_REMOTE 检查可确保它仅在云端会话中运行。

重要提示：-R 标志

由于沙盒代理的限制，gh 可能无法自动检测仓库。请使用 -R owner/repo 标志：

gh pr create -R codervisor/myrepo --title "..." --body "..."
gh issue list -R codervisor/myrepo

GitHub Copilot 编码 Agent

Copilot 编码 Agent 使用 .github/copilot-setup-steps.yml。系统已预装 gh CLI；你只需对其进行身份验证。

在 .github/copilot-setup-steps.yml 添加此文件：

name: "Copilot Setup Steps"

on: repository_dispatch

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Authenticate gh CLI
        run: gh auth status
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

完整模板（含依赖项安装）请参见 templates/copilot-setup-steps.yml。

设置脚本、SessionStart Hook 与 copilot-setup-steps 的对比

	设置脚本	SessionStart Hook	copilot-setup-steps.yml
平台	仅限 Claude Code 云端	Claude Code（本地 + 云端）	仅限 GitHub Copilot Agent
配置位置	环境设置界面	仓库中的 .claude/settings.json	.github/copilot-setup-steps.yml
运行时机	Claude 启动前	Claude 启动后	Copilot Agent 启动前
恢复会话时运行	否（仅限新会话）	是（每次会话）	是
网络	需要访问软件包仓库	需要访问软件包仓库	可访问完整的 GitHub Actions 网络

Agent 常用的 gh 命令

# PRs (use -R in Claude Code cloud)
gh pr create -R owner/repo --title "..." --body "..."
gh pr list -R owner/repo
gh pr view -R owner/repo
gh pr merge -R owner/repo --squash --delete-branch

# Issues
gh issue list -R owner/repo
gh issue view 42 -R owner/repo
gh issue create -R owner/repo --title "..." --body "..."

# API (for anything not covered by subcommands)
gh api repos/owner/repo/actions/runs

常见问题

症状	原因	解决方法
gh: command not found	未安装（Claude Code 云端）	在设置脚本中添加 apt install -y gh
HTTP 401 / 身份验证错误	未设置 GH_TOKEN	在设置界面中将其添加为环境变量
推送时出现 HTTP 403	令牌缺少 repo 权限范围	重新生成具有 repo 权限范围的 PAT
could not determine repo	沙盒代理隐藏了 git 远程仓库	使用 -R owner/repo 标志
gh pr create 失败	没有上游分支	先使用 git push -u origin <branch> 推送
设置脚本失败	无法访问网络	将网络设置为“Limited”（默认）或“Full”

参考资料

• references/cloud-auth.md — 令牌身份验证、权限范围、代理详情和故障排除
• references/copilot-setup-steps.md — 自定义 Copilot 设置工作流的完整指南

设置与激活

npx skills add -g onsager-ai/dev-skills --skill github-integration -a claude-code -y

当用户提到“云端 gh”、“github 集成”、“设置脚本”、“copilot 设置步骤”，或云端环境中的 gh 身份验证失败时自动激活。