---
name: github
description: "Use this skill whenever the user wants to interact with git repositories or GitHub via the command line. Triggers include: cloning repos, checking out branches, committing or pushing changes, reading repo structure, creating or merging pull requests, listing issues, managing GitHub releases, or any task involving git CLI or gh CLI. Authentication for both git (HTTPS) and gh is handled transparently by the sidecar proxy — no token management is required. A fake token in either GH_TOKEN or ~/.config/gh/hosts.yml is sufficient; the proxy injects real credentials automatically."
license: "Copyright (c) Airia LLC. All rights reserved."
---

# git & gh CLI

## Overview

Two CLI tools are available in the sandbox:

| Tool | Version | Purpose |
|------|---------|---------|
| `git` | 2.43.0 | Local repository operations |
| `gh` | 2.89.0 | GitHub API operations (PRs, issues, releases, etc.) |

Authentication for both is handled by the sidecar proxy. No real tokens are needed.

---

## Authentication Setup

### gh CLI — Config File (persistent)

Write a fake token to `~/.config/gh/hosts.yml`. The sidecar proxy intercepts all GitHub API calls and injects real credentials automatically.

```bash
mkdir -p ~/.config/gh && cat > ~/.config/gh/hosts.yml << 'EOF'
github.com:
    oauth_token: fake
    git_protocol: https
    user: placeholder
EOF
```

To discover the authenticated username after setup:

```bash
gh api user --jq '.login'
```

Verify auth works:

```bash
gh auth status
# Expected: ✓ Logged in to github.com account <user> (~/.config/gh/hosts.yml)
```

### gh CLI — Environment Variable (per-command)

If the config file is not present, prefix commands with `GH_TOKEN=fake`:

```bash
GH_TOKEN=fake gh auth status
GH_TOKEN=fake gh repo list
```

### git CLI (HTTPS)

Git operations over HTTPS are also proxied. No credential configuration is required. Always use HTTPS URLs — SSH is not supported.

```bash
# Correct
git clone https://github.com/AiriaLLC/airia-sandbox.git

# Do NOT use SSH
git clone git@github.com:AiriaLLC/airia-sandbox.git  # will fail
```

---

## git Quick Reference

### Clone

```bash
git clone https://github.com/AiriaLLC/airia-sandbox.git /home/sandbox/airia-sandbox
```

### Status & Diff

```bash
git -C /home/sandbox/airia-sandbox status
git -C /home/sandbox/airia-sandbox diff
git -C /home/sandbox/airia-sandbox log --oneline -10
```

### Branching

```bash
git -C /home/sandbox/airia-sandbox checkout -b my-branch
git -C /home/sandbox/airia-sandbox checkout main
git -C /home/sandbox/airia-sandbox branch -a
```

### Stage & Commit

```bash
git -C /home/sandbox/airia-sandbox add .
git -C /home/sandbox/airia-sandbox add path/to/file.txt
git -C /home/sandbox/airia-sandbox commit -m "your message"
```

### Push

```bash
git -C /home/sandbox/airia-sandbox push origin my-branch
```

### Pull / Fetch

```bash
git -C /home/sandbox/airia-sandbox pull
git -C /home/sandbox/airia-sandbox fetch origin
```

### Set Identity (required for commits)

```bash
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
```

---

## gh Quick Reference

### Repos

```bash
# List repos for a user or org
gh repo list AiriaLLC

# View a repo
gh repo view AiriaLLC/airia-sandbox

# Clone via gh
gh repo clone AiriaLLC/airia-sandbox /home/sandbox/airia-sandbox
```

### Pull Requests

```bash
# List PRs
gh pr list --repo AiriaLLC/airia-sandbox

# View a PR
gh pr view 42 --repo AiriaLLC/airia-sandbox

# Create a PR
gh pr create --repo AiriaLLC/airia-sandbox \
  --title "My PR title" \
  --body "Description of changes" \
  --base main \
  --head my-branch

# Merge a PR
gh pr merge 42 --repo AiriaLLC/airia-sandbox --squash
```

### Issues

```bash
# List issues
gh issue list --repo AiriaLLC/airia-sandbox

# View an issue
gh issue view 10 --repo AiriaLLC/airia-sandbox

# Create an issue
gh issue create --repo AiriaLLC/airia-sandbox \
  --title "Bug: something broken" \
  --body "Steps to reproduce..."

# Close an issue
gh issue close 10 --repo AiriaLLC/airia-sandbox
```

### Releases

```bash
# List releases
gh release list --repo AiriaLLC/airia-sandbox

# View a release
gh release view v1.0.0 --repo AiriaLLC/airia-sandbox

# Create a release
gh release create v1.2.0 --repo AiriaLLC/airia-sandbox \
  --title "v1.2.0" \
  --notes "Release notes here"
```

### Workflows (GitHub Actions)

```bash
# List workflows
gh workflow list --repo AiriaLLC/airia-sandbox

# Trigger a workflow
gh workflow run deploy.yml --repo AiriaLLC/airia-sandbox

# View recent runs
gh run list --repo AiriaLLC/airia-sandbox

# Watch a run live
gh run watch --repo AiriaLLC/airia-sandbox
```

### Files (read without cloning)

```bash
# View a file from a repo without cloning
gh api repos/AiriaLLC/airia-sandbox/contents/README.md \
  --jq '.content' | base64 -d
```

---

## Common Patterns

### Clone, edit, commit, push, open PR

```bash
REPO=/home/sandbox/airia-sandbox

git clone https://github.com/AiriaLLC/airia-sandbox.git $REPO
git -C $REPO checkout -b fix/my-fix

# ... edit files in $REPO ...

git -C $REPO add .
git -C $REPO commit -m "fix: description of change"
git -C $REPO push origin fix/my-fix

gh pr create --repo AiriaLLC/airia-sandbox \
  --title "fix: description of change" \
  --body "What and why." \
  --base main \
  --head fix/my-fix
```

### Inspect a repo without cloning

```bash
# List top-level files
gh api repos/AiriaLLC/airia-sandbox/contents/ --jq '.[].name'

# Get a specific file
gh api repos/AiriaLLC/airia-sandbox/contents/README.md \
  --jq '.content' | base64 -d
```

---

## Notes

- Always use `--repo ORG/REPO` with `gh` to avoid ambiguity.
- Use `-C /path/to/repo` with `git` to avoid `cd`ing into directories.
- The sidecar proxy handles HTTPS credential injection — never use SSH URLs.
- To resolve the authenticated GitHub username at runtime: `gh api user --jq '.login'`
