{“content”:”---\nname: github-auth\ndescription: Set up GitHub authentication for the agent using git (universally available) or the gh CLI. Covers HTTPS tokens, SSH keys, credential helpers, and gh auth — with a detection flow to pick the right method automatically.\nversion: 1.1.0\nauthor: Hermes Agent\nlicense: MIT\nmetadata:\n hermes:\n tags: [GitHub, Authentication, Git, gh-cli, SSH, Setup]\n related_skills: [github-pr-workflow, github-code-review, github-issues, github-repo-management]\n---\n\n# GitHub Authentication Setup\n\nThis skill sets up authentication so the agent can work with GitHub repositories, PRs, issues, and CI. It covers two paths:\n\n- git (always available) — uses HTTPS personal access tokens or SSH keys\n- gh CLI (if installed) — richer GitHub API access with a simpler auth flow\n\n## Detection Flow\n\nWhen a user asks you to work with GitHub, run this check first:\n\nbash\n# Check what's available\ngit --version\ngh --version 2>/dev/null || echo \"gh not installed\"\n\n# Check if already authenticated\ngh auth status 2>/dev/null || echo \"gh not authenticated\"\ngit config --global credential.helper 2>/dev/null || echo \"no git credential helper\"\n\n\nDecision tree:\n1. If gh auth status shows authenticated → you’re good, use gh for everything\n2. If gh is installed but not authenticated → use “gh auth” method below\n3. If gh is not installed → use “git-only” method below (no sudo needed)\n\n---\n\n## Method 1: Git-Only Authentication (No gh, No sudo)\n\nThis works on any machine with git installed. No root access needed.\n\n### Option A: HTTPS with Personal Access Token (Recommended)\n\nThis is the most portable method — works everywhere, no SSH config needed.\n\nStep 1: Create a personal access token\n\nTell the user to go to: https://github.com/settings/tokens**\n\n- Click “Generate new token (classic)“\n- Give it a name like “hermes-agent”\n- Select scopes:\n - repo (full repository access — read, write, push, PRs)\n - workflow (trigger and manage GitHub Actions)\n - read:org (if working with organization repos)\n- Set expiration (90 days is a good default)\n- Copy the token — it won’t be shown again\n\nStep 2: Configure git to store the token**\n\nbash\n# Set up the credential helper to cache credentials\n# \"store\" saves to ~/.git-credentials in plaintext (simple, persistent)\ngit config --global credential.helper store\n\n# Now do a test operation that triggers auth — git will prompt for credentials\n# Username: <their-github-username>\n# Password: <paste the personal access token, NOT their GitHub password>\ngit ls-remote https://github.com/<their-username>/<any-repo>.git\n\n\nAfter entering credentials once, they’re saved and reused for all future operations.\n\nAlternative: cache helper (credentials expire from memory)\n\nbash\n# Cache in memory for 8 hours (28800 seconds) instead of saving to disk\ngit config --global credential.helper 'cache --timeout=28800'\n\n\nAlternative: set the token directly in the remote URL (per-repo)\n\nbash\n# Embed token in the remote URL (avoids credential prompts entirely)\ngit remote set-url origin https://<username>:<token>@github.com/<owner>/<repo>.git\n\n\nStep 3: Configure git identity\n\nbash\n# Required for commits — set name and email\ngit config --global user.name \"Their Name\"\ngit config --global user.email \"[email protected]\"\n\n\nStep 4: Verify\n\nbash\n# Test push access (this should work without any prompts now)\ngit ls-remote https://github.com/<their-username>/<any-repo>.git\n\n# Verify identity\ngit config --global user.name\ngit config --global user.email\n\n\n### Option B: SSH Key Authentication\n\nGood for users who prefer SSH or already have keys set up.\n\nStep 1: Check for existing SSH keys\n\nbash\nls -la ~/.ssh/id_*.pub 2>/dev/null || echo \"No SSH keys found\"\n\n\nStep 2: Generate a key if needed\n\nbash\n# Generate an ed25519 key (modern, secure, fast)\nssh-keygen -t ed25519 -C \"[email protected]\" -f ~/.ssh/id_ed25519 -N \"\"\n\n# Display the public key for them to add to GitHub\ncat ~/.ssh/id_ed25519.pub\n\n\nTell the user to add the public key at: https://github.com/settings/keys**\n- Click “New SSH key”\n- Paste the public key content\n- Give it a title like “hermes-agent-bash\nssh -T [email protected]\n# Expected: \"Hi <username>! You've successfully authenticated...\"\n\n\nStep 4: Configure git to use SSH for GitHub\n\nbash\n# Rewrite HTTPS GitHub URLs to SSH automatically\ngit config --global url.\"[email protected]:\".insteadOf \"https://github.com/\"\n\n\nStep 5: Configure git identity\n\nbash\ngit config --global user.name \"Their Name\"\ngit config --global user.email \"[email protected]\"\n\n\n---\n\n## Method 2: gh CLI Authentication\n\nIf gh is installed, it handles both API access and git credentials in one step.\n\n### Interactive Browser Login (Desktop)\n\nbash\ngh auth login\n# Select: GitHub.com\n# Select: HTTPS\n# Authenticate via browser\n\n\n### Token-Based Login (Headless / SSH Servers)\n\nbash\necho \"<THEIR_TOKEN>\" | gh auth login --with-token\n\n# Set up git credentials through gh\ngh auth setup-git\n\n\n### Verify\n\nbash\ngh auth status\n\n\n---\n\n## Using the GitHub API Without gh\n\nWhen gh is not available, you can still access the full GitHub API using curl with a personal access token. This is how the other GitHub skills implement their fallbacks.\n\n### Setting the Token for API Calls\n\nbash\n# Option 1: Export as env var (preferred — keeps it out of commands)\nexport GITHUB_TOKEN=\"<token>\"\n\n# Then use in curl calls:\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n https://api.github.com/user\n\n\n### Extracting the Token from Git Credentials\n\nIf git credentials are already configured (via credential.helper store), the token can be extracted:\n\nbash\n# Read from git credential store\ngrep \"github.com\" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\\([^@]*\\)@.*|\\1|'\n\n\n### Helper: Detect Auth Method\n\nUse this pattern at the start of any GitHub workflow:\n\nbash\n# Try gh first, fall back to git + curl\nif command -v gh &>/dev/null && gh auth status &>/dev/null; then\n echo \"AUTH_METHOD=gh\"\nelif [ -n \"$GITHUB_TOKEN\" ]; then\n echo \"AUTH_METHOD=curl\"\nelif [ -f ~/.hermes/.env ] && grep -q \"^GITHUB_TOKEN=\" ~/.hermes/.env; then\n export GITHUB_TOKEN=$(grep \"^GITHUB_TOKEN=\" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\\n\\r')\n echo \"AUTH_METHOD=curl\"\nelif grep -q \"github.com\" ~/.git-credentials 2>/dev/null; then\n export GITHUB_TOKEN=$(grep \"github.com\" ~/.git-credentials | head -1 | sed 's|https://[^:]*:\\([^@]*\\)@.*|\\1|')\n echo \"AUTH_METHOD=curl\"\nelse\n echo \"AUTH_METHOD=none\"\n echo \"Need to set up authentication first\"\nfi\n\n\n---\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| git push asks for password | GitHub disabled password auth. Use a personal access token as the password, or switch to SSH |\n| remote: Permission to X denied | Token may lack repo scope — regenerate with correct scopes |\n| fatal: Authentication failed | Cached credentials may be stale — run git credential reject then re-authenticate |\n| ssh: connect to host github.com port 22: Connection refused | Try SSH over HTTPS port: add Host github.com with Port 443 and Hostname ssh.github.com to ~/.ssh/config |\n| Credentials not persisting | Check git config --global credential.helper — must be store or cache |\n| Multiple GitHub accounts | Use SSH with different keys per host alias in ~/.ssh/config, or per-repo credential URLs |\n| gh: command not found + no sudo | Use git-only Method 1 above — no installation needed |\n”}