Back to Details

github-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub Integration

GitHub集成

Enable 
gh
CLI access in Claude Code cloud and GitHub Copilot coding agent environments so agents can create PRs, manage issues, and interact with GitHub APIs.
在Claude Code云和GitHub Copilot编码代理环境中启用
gh
CLI访问权限，让代理能够创建PR、管理议题并与GitHub API交互。

When to Use This Skill

何时使用此技能

Activate when:
  • User wants cloud AI agents to use 
    gh
    (PRs, issues, releases, API calls)
  • User needs to install 
    gh
    in Claude Code cloud sessions
  • User wants to add 
    copilot-setup-steps.yml
    for GitHub Copilot agents
  • gh
    commands fail with auth or "not found" errors in a cloud session
  • User wants to enable GitHub integration for any cloud-based AI coding agent
在以下场景激活：
  • 用户希望云端AI代理使用
    gh
    （处理PR、议题、版本发布、API调用）
  • 用户需要在Claude Code云会话中安装
    gh
  • 用户希望为GitHub Copilot代理添加
    copilot-setup-steps.yml
    文件
  • 云会话中
    gh
    命令因认证或“未找到”错误失败
  • 用户希望为任何云端AI编码代理启用GitHub集成

Decision Tree

决策树

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
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

Two Environments, Two Approaches

两种环境，两种方案

Claude Code Cloud (claude.ai/code)

Claude Code云（claude.ai/code）

Claude Code cloud runs sessions in Anthropic-managed VMs. The 
gh
CLI is not pre-installed. You need two things:
  1. Setup script — installs 
    gh
    when the session starts
  2. GH_TOKEN
    env var     — authenticates 
    gh
    with your GitHub PAT
Claude Code云在Anthropic管理的VM中运行会话。
gh
CLI未预装，你需要完成两项配置：
  1. 初始化脚本 —— 会话启动时安装
    gh
  2. GH_TOKEN
    环境变量     —— 使用你的GitHub PAT认证
    gh

Quick Start: Setup Script

快速开始：初始化脚本

In the Claude Code web UI: Environment Settings → Setup script:
bash
#!/bin/bash
apt update && apt install -y gh
Then add 
GH_TOKEN
as an environment variable with your GitHub Personal Access Token (needs 
repo
scope).
在Claude Code网页UI中：环境设置 → 初始化脚本：
bash
#!/bin/bash
apt update && apt install -y gh
然后添加
GH_TOKEN
作为环境变量，值为你的GitHub个人访问令牌（需要
repo
权限范围）。

Alternative: SessionStart Hook (repo-portable)

替代方案：SessionStart钩子（仓库可移植）

Add to 
.claude/settings.json
in your repo:
json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "if [ \"$CLAUDE_CODE_REMOTE\" = \"true\" ]; then apt update && apt install -y gh; fi",
            "timeout": 120
          }
        ]
      }
    ]
  }
}
The 
CLAUDE_CODE_REMOTE
check ensures it only runs in cloud sessions.
在仓库的
.claude/settings.json
中添加：
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
检查确保脚本仅在云会话中运行。

Important: The 
-R
Flag

重要提示：
-R
参数

Due to the sandbox proxy, 
gh
may not auto-detect the repo. Use the 
-R owner/repo
flag:
bash
gh pr create -R codervisor/myrepo --title "..." --body "..."
gh issue list -R codervisor/myrepo
由于沙箱代理，
gh
可能无法自动检测仓库。请使用
-R owner/repo
参数：
bash
gh pr create -R codervisor/myrepo --title "..." --body "..."
gh issue list -R codervisor/myrepo

GitHub Copilot Coding Agent

GitHub Copilot编码代理

Copilot coding agents use 
.github/copilot-setup-steps.yml
. The 
gh
CLI is pre-installed; you just need to authenticate it.
Add this file at 
.github/copilot-setup-steps.yml
:
yaml
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 }}
See 
templates/copilot-setup-steps.yml
for a full template with dependency installation.
Copilot编码代理使用
.github/copilot-setup-steps.yml
。
gh
CLI已预装，你只需完成认证配置。
在
.github/copilot-setup-steps.yml
路径下添加以下文件：
yaml
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
。

Setup Scripts vs SessionStart Hooks vs copilot-setup-steps

初始化脚本 vs SessionStart钩子 vs copilot-setup-steps

Setup scriptsSessionStart hookscopilot-setup-steps.yml
PlatformClaude Code cloud onlyClaude Code (local + cloud)GitHub Copilot agents only
Configured inEnvironment settings UI
.claude/settings.json
in repo
.github/copilot-setup-steps.yml
RunsBefore Claude launchesAfter Claude launchesBefore Copilot agent launches
Runs on resumeNo (new sessions only)Yes (every session)Yes
NetworkNeeds registry accessNeeds registry accessFull GitHub Actions network
初始化脚本SessionStart钩子copilot-setup-steps.yml
平台仅Claude Code云Claude Code（本地+云端）仅GitHub Copilot代理
配置位置环境设置UI仓库中的
.claude/settings.json
.github/copilot-setup-steps.yml
运行时机Claude启动前Claude启动后Copilot代理启动前
恢复会话时运行否（仅新会话）是（每次会话）是
网络需要访问镜像源需要访问镜像源完整GitHub Actions网络权限

Common gh Commands for Agents

代理常用gh命令

bash
undefined
bash
undefined

PRs (use -R in Claude Code cloud)

PRs（Claude Code云中需使用-R参数）

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
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 "..."
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)

API（子命令未覆盖的操作）

gh api repos/owner/repo/actions/runs
undefined
gh api repos/owner/repo/actions/runs
undefined

Pitfalls

常见陷阱

SymptomCauseFix
gh: command not found
Not installed (Claude Code cloud)Add 
apt install -y gh
to setup script
HTTP 401
/ auth error
GH_TOKEN
not set		Add to environment variables in settings UI
HTTP 403
on push		Token lacks 
repo
scope		Regenerate PAT with 
repo
scope
could not determine repo
Sandbox proxy hides git remoteUse 
-R owner/repo
flag
gh pr create
fails		No upstream branchPush with 
git push -u origin <branch>
first
Setup script failsNo network accessSet network to "Limited" (default) or "Full"
症状原因修复方案
gh: command not found
未安装（Claude Code云）在初始化脚本中添加
apt install -y gh
HTTP 401
/ 认证错误
GH_TOKEN
未设置		在设置UI的环境变量中添加
推送时出现
HTTP 403
令牌缺少
repo
权限范围		重新生成带有
repo
权限的PAT
could not determine repo
沙箱代理隐藏了git远程仓库使用
-R owner/repo
参数
gh pr create
失败		无上游分支先执行
git push -u origin <branch>
推送
初始化脚本执行失败无网络访问权限将网络设置为“受限”（默认）或“完全”

References

参考资料

  • references/cloud-auth.md
    — Token auth, scopes, proxy details, troubleshooting
  • references/copilot-setup-steps.md
    — Full guide to customizing the Copilot setup workflow
  • references/cloud-auth.md
    —— 令牌认证、权限范围、代理细节、故障排查
  • references/copilot-setup-steps.md
    —— 自定义Copilot初始化工作流的完整指南

Setup & Activation

安装与激活

bash
npx skills add -g onsager-ai/dev-skills --skill github-integration -a claude-code -y
Auto-activates when: user mentions "gh in cloud", "github integration", "setup script", "copilot setup steps", or 
gh
auth failures in cloud environments.
bash
npx skills add -g onsager-ai/dev-skills --skill github-integration -a claude-code -y
当用户提及“gh in cloud”、“github integration”、“setup script”、“copilot setup steps”或云环境中
gh
认证失败时，将自动激活。