GitHub Integration

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.

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

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

Two Environments, Two Approaches

Claude Code Cloud (claude.ai/code)

Claude Code cloud runs sessions in Anthropic-managed VMs. The gh CLI is not pre-installed. You need two things:

Setup script — installs gh when the session starts
GH_TOKEN env var — authenticates gh with your GitHub PAT

Quick Start: Setup Script

In the Claude Code web UI: Environment Settings → Setup script:

#!/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).

Alternative: SessionStart Hook (repo-portable)

Add to .claude/settings.json in your repo:

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

Important: The `-R` Flag

Due to the sandbox proxy, gh may not auto-detect the repo. Use the -R owner/repo flag:

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

GitHub Copilot Coding Agent

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:

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.

Setup Scripts vs SessionStart Hooks vs copilot-setup-steps

	Setup scripts	SessionStart hooks	copilot-setup-steps.yml
Platform	Claude Code cloud only	Claude Code (local + cloud)	GitHub Copilot agents only
Configured in	Environment settings UI	`.claude/settings.json` in repo	`.github/copilot-setup-steps.yml`
Runs	Before Claude launches	After Claude launches	Before Copilot agent launches
Runs on resume	No (new sessions only)	Yes (every session)	Yes
Network	Needs registry access	Needs registry access	Full GitHub Actions network

Common gh Commands for Agents

# 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

Pitfalls

Symptom	Cause	Fix
`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 remote	Use `-R owner/repo` flag
`gh pr create` fails	No upstream branch	Push with `git push -u origin <branch>` first
Setup script fails	No network access	Set network to "Limited" (default) or "Full"

References

references/cloud-auth.md — Token auth, scopes, proxy details, troubleshooting
references/copilot-setup-steps.md — Full guide to customizing the Copilot setup workflow

Setup & Activation

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.

github-integration