github-repo-management

# GitHub Repository Management Create, clone, fork, configure, and manage GitHub repositories. Each section shows `gh` first, then the `git` + `curl` fallback. ## Prerequisites - Authenticated with GitHub (see `github-auth` skill) ### Setup ```bash if command -v gh &>/dev/null && gh auth status &>/dev/null; then AUTH="gh" else AUTH="git" if [ -z "$GITHUB_TOKEN" ]; then if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r') elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|') fi fi fi # Get your GitHub username (needed for several operations) if [ "$AUTH" = "gh" ]; then GH_USER=$(gh api user --jq '.login') else GH_USER=$(curl -s -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user | python3 -c "import sys,json; print(json.load(sys.stdin)['login'])") fi ``` If you're inside a repo already: ```bash REMOTE_URL=$(git remote get-url origin) OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||') OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1) REPO=$(echo "$OWNER_REPO" | cut -d/ -f2) ``` --- ## 1. Cloning Repositories Cloning is pure `git` — works identically either way: ```bash # Clone via HTTPS (works with credential helper or token-embedded URL) git clone https://github.com/owner/repo-name.git # Clone into a specific directory git clone https://github.com/owner/repo-name.git ./my-local-dir # Shallow clone (faster for large repos) git clone --depth 1 https://github.com/owner/repo-name.git # Clone a specific branch git clone --branch develop https://github.com/owner/repo-name.git # Clone via SSH (if SSH is configured) git clone <email redacted>:owner/repo-name.git ``` **With gh (shorthand):** ```bash gh repo clone owner/repo-name gh repo clone owner/repo-name -- --depth 1 ``` ## 2. Creating Repositories **With gh:** ```bash # Create a public repo and clone it gh repo create my-new-project --public --clone # Private, with description and license gh repo create my-new-project --private --description "A useful tool" --license MIT --clone # Under an organization gh repo create my-org/my-new-project --public --clone # From existing local directory cd /path/to/existing/project gh repo create my-project --source . --public --push ``` **With git + curl:** ```bash # Create the remote repo via API curl -s -X POST \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/user/repos \ -d '{ "name": "my-new-project", "description": "A useful tool", "private": false, "auto_init": true, "license_template": "mit" }' # Clone it git clone https://github.com/$GH_USER/my-new-project.git cd my-new-project # -- OR -- push an existing local directory to the new repo cd /path/to/existing/project git init git add . git commit -m "Initial commit" git remote add origin https://github.com/$GH_USER/my-new-project.git git push -u origin main ``` To create under an organization: ```bash curl -s -X POST \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/orgs/my-org/repos \ -d '{"name": "my-new-project", "private": false}' ``` ### From a Template **With gh:** ```bash gh repo create my-new-app --template owner/template-repo --public --clone ``` **With curl:** ```bash curl -s -X POST \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/owner/template-repo/generate \ -d '{"owner": "'"$GH_USER"'", "name": "my-new-app", "private": false}' ``` ## 3. Forking Repositories **With gh:** ```bash gh repo fork owner/repo-name --clone ``` **With git + curl:** ```bash # Create the fork via API curl -s -X POST \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/owner/repo-name/forks # Wait a moment for GitHub to create it, then clone sleep 3 git clone https://github.com/$GH_USER/repo-name.git cd repo-name # Add the original repo as "upstream" remote git remote add upstream https://github.com/owner/repo-name.git ``` ### Keeping a Fork in Sync ```bash # Pure git — works everywhere git fetch upstream git checkout main git merge upstream/main git push origin main ``` **With gh (shortcut):** ```bash gh repo sync $GH_USER/repo-name ``` ## 4. Repository Information **With gh:** ```bash gh repo view owner/repo-name gh repo list --limit 20 gh search repos "machine learning" --language python --sort stars ``` **With curl:** ```bash # View repo details curl -s \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/$OWNER/$REPO \ | python3 -c " import sys, json r = json.load(sys.stdin) print(f\"Name: {r['full_name']}\") print(f\"Description: {r['description']}\") print(f\"Stars: {r['stargazers_count']} Forks: {r['forks_count']}\") print(f\"Default branch: {r['default_branch']}\") print(f\"Language: {r['language']}\")" # List your repos curl -s \ -H "Authorization: token $GITHUB_TOKEN" \ "https://api.github.com/user/repos?per_page=20&sort=updated" \ | python3 -c " import sys, json for r in json.load(sys.stdin): vis = 'private' if r['private'] else 'public' print(f\" {r['full_name']:40} {vis:8} {r.get('language', ''):10} ★{r['stargazers_count']}\")" # Search repos curl -s \ "https://api.github.com/search/repositories?q=machine+learning+language:python&sort=stars&per_page=10" \ | python3 -c " import sys, json for r in json.load(sys.stdin)['items']: print(f\" {r['full_name']:40} ★{r['stargazers_count']:6} {r['description'][:60] if r['description'] else ''}\")" ``` ## 5. Repository Settings **With gh:** ```bash gh repo edit --description "Updated description" --visibility public gh repo edit --enable-wiki=false --enable-issues=true gh repo edit --default-branch main gh repo edit --add-topic "machine-learning,python" gh repo edit --enable-auto-merge ``` **With curl:** ```bash curl -s -X PATCH \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/$OWNER/$REPO \ -d '{ "description": "Updated description", "has_wiki": false, "has_issues": true, "allow_auto_merge": true }' # Update topics curl -s -X PUT \ -H "Authorization: token $GITHUB_TOKEN" \ -H "Accept: application/vnd.github.mercy-preview+json" \ https://api.github.com/repos/$OWNER/$REPO/topics \ -d '{"names": ["machine-learning", "python", "automation"]}' ``` ## 6. Branch Protection ```bash # View current protection curl -s \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/$OWNER/$REPO/branches/main/protection # Set up branch protection curl -s -X PUT \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/$OWNER/$REPO/branches/main/protection \ -d '{ "required_status_checks": { "strict": true, "contexts": ["ci/test", "ci/lint"] }, "enforce_admins": false, "required_pull_request_reviews": { "required_approving_review_count": 1 }, "restrictions": null }' ``` ## 7. Secrets Management (GitHub Actions) **With gh:** ```bash gh secret set API_KEY --body "your-secret-value" gh secret set SSH_KEY < ~/.ssh/id_rsa gh secret list gh secret delete API_KEY ``` **With curl:** Secrets require encryption with the repo's public key — more involved via API: ```bash # Get the repo's public key for encrypting secrets curl -s \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/$OWNER/$REPO/actions/secrets/public-key # Encrypt and set (requires Python with PyNaCl) python3 -c " from base64 import b64encode from nacl import encoding, public import json, sys # Get the public key key_id = '<key_id_from_above>' public_key = '<base64_key_from_above>' # Encrypt sealed = public.SealedBox( public.PublicKey(public_key.encode('utf-8'), encoding.Base64Encoder) ).encrypt('your-secret-value'.encode('utf-8')) print(json.dumps({ 'encrypted_value': b64encode(sealed).decode('utf-8'), 'key_id': key_id }))" # Then PUT the encrypted secret curl -s -X PUT \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/$OWNER/$REPO/actions/secrets/API_KEY \ -d '<output from python script above>' # List secrets (names only, values hidden) curl -s \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/$OWNER/$REPO/actions/secrets \ | python3 -c " import sys, json for s in json.load(sys.stdin)['secrets']: print(f\" {s['name']:30} updated: {s['updated_at']}\")" ``` Note: For secrets, `gh secret set` is dramatically simpler. If setting secrets is needed and `gh` isn't available, recommend installing it for just that operation. ## 8. Releases **With gh:** ```bash gh release create v1.0.0 --title "v1.0.0" --generate-notes gh release create v2.0.0-rc1 --draft --prerelease --generate-notes gh release create v1.0.0 ./dist/binary --title "v1.0.0" --notes "Release notes" gh release list gh release download v1.0.0 --dir ./downloads ```