From f6d5f0b2deb5ef18c70d10ca226fbda043d9cadf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 7 Mar 2026 23:05:41 +0000 Subject: [PATCH 1/2] Initial plan From 83eb670e47a260c95828aed8b9b671bb03b645ff Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 7 Mar 2026 23:08:32 +0000 Subject: [PATCH 2/2] docs: add SSH/GitHub authentication setup guide and helper script Co-authored-by: deilert00 <139483703+deilert00@users.noreply.github.com> --- README.md | 37 ++++ docs/SSH_GITHUB_SETUP.md | 408 +++++++++++++++++++++++++++++++++++++++ scripts/check-ssh.sh | 115 +++++++++++ 3 files changed, 560 insertions(+) create mode 100644 docs/SSH_GITHUB_SETUP.md create mode 100755 scripts/check-ssh.sh diff --git a/README.md b/README.md index 3f50fc0..1c3d988 100644 --- a/README.md +++ b/README.md @@ -232,6 +232,43 @@ Note: - Baseline support runbook and command usage: - `docs/ADMIN_SUPPORT_RUNBOOK.md` +## GitHub Authentication (SSH Setup) + +This project uses SSH for Git operations. +Full guide: [`docs/SSH_GITHUB_SETUP.md`](docs/SSH_GITHUB_SETUP.md) + +### Quick start + +```bash +# 1. Generate a key (skip if you already have one) +ssh-keygen -t ed25519 -C "you@example.com" + +# 2. Copy the public key and add it to github.com/settings/keys +cat ~/.ssh/id_ed25519.pub + +# 3. Verify connection — the response shows which GitHub account is active +ssh -T git@github.com + +# 4. Run the repo helper to diagnose any issues +bash scripts/check-ssh.sh +``` + + + + +### Troubleshooting at a glance + +| Symptom | Fix | +|---|---| +| Settings → SSH keys page is **empty** | Make sure you are in your **personal** account settings, not an organization — go to `https://github.com/settings/keys` | +| Signed in as the wrong GitHub account | Sign out → sign in as the correct user → re-add the key | +| `Permission denied (publickey)` | Load the key: `ssh-add ~/.ssh/id_ed25519` | +| SAML/SSO error from organization | Visit `https://github.com/settings/keys` → Configure SSO → Authorize | +| Corporate firewall blocks SSH | Use the [PAT fallback](docs/SSH_GITHUB_SETUP.md#pat-fallback-https-authentication) | + +See [`docs/SSH_GITHUB_SETUP.md`](docs/SSH_GITHUB_SETUP.md) for the full step-by-step +instructions, screenshot placeholders, and all troubleshooting scenarios. + ## Troubleshooting - `Executable doesn't exist` / Playwright browser missing: diff --git a/docs/SSH_GITHUB_SETUP.md b/docs/SSH_GITHUB_SETUP.md new file mode 100644 index 0000000..f9687ef --- /dev/null +++ b/docs/SSH_GITHUB_SETUP.md @@ -0,0 +1,408 @@ +# GitHub SSH Authentication Setup + +This guide covers generating an SSH key, adding it to your GitHub account, verifying the +correct account is active, and using a Personal Access Token (PAT) as a fallback. + +--- + +## Table of Contents + +1. [Why SSH?](#why-ssh) +2. [Prerequisites](#prerequisites) +3. [Step 1 — Generate an SSH Key Pair](#step-1--generate-an-ssh-key-pair) +4. [Step 2 — Add the Public Key to GitHub](#step-2--add-the-public-key-to-github) +5. [Step 3 — Verify the SSH Connection](#step-3--verify-the-ssh-connection) +6. [Step 4 — Configure Git to Use SSH](#step-4--configure-git-to-use-ssh) +7. [PAT Fallback (HTTPS Authentication)](#pat-fallback-https-authentication) +8. [Troubleshooting](#troubleshooting) + - [Settings shows an empty SSH key list](#settings-shows-an-empty-ssh-key-list) + - [Permission denied (publickey)](#permission-denied-publickey) + - [Wrong account is authenticated](#wrong-account-is-authenticated) + - [Organization SSO restrictions](#organization-sso-restrictions) + +--- + +## Why SSH? + +SSH key authentication avoids entering a username and password on every `git push`/`git pull`. +Unlike HTTPS with a cached password, SSH keys are tied to a specific machine and revocable +individually from your GitHub account settings. + +--- + +## Prerequisites + +- Git installed locally (`git --version`) +- OpenSSH installed (`ssh -V`) — ships with macOS, modern Windows (OpenSSH optional feature), + and all major Linux distributions +- A GitHub account + +--- + +## Step 1 — Generate an SSH Key Pair + +Open a terminal and run: + +```bash +ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +> **Note:** Replace `your_email@example.com` with the email address associated with your +> GitHub account. This comment is embedded in the key for identification purposes only. + +When prompted: + +- **Enter file in which to save the key:** press **Enter** to accept the default + (`~/.ssh/id_ed25519`), or type a custom path. +- **Enter passphrase:** choose a strong passphrase (recommended) or press **Enter** for none. + + + + +This creates two files: + +| File | Purpose | +|---|---| +| `~/.ssh/id_ed25519` | **Private key** — never share this | +| `~/.ssh/id_ed25519.pub` | **Public key** — this is what you add to GitHub | + +### Add the key to the SSH agent + +Start the agent and add your new private key so it is available in the current session: + +```bash +# macOS / Linux +eval "$(ssh-agent -s)" +ssh-add ~/.ssh/id_ed25519 +``` + +```powershell +# Windows (PowerShell, OpenSSH service must be running) +Start-Service ssh-agent +ssh-add $env:USERPROFILE\.ssh\id_ed25519 +``` + +--- + +## Step 2 — Add the Public Key to GitHub + +1. Copy your public key to the clipboard: + + ```bash + # macOS + pbcopy < ~/.ssh/id_ed25519.pub + + # Linux (xclip) + xclip -selection clipboard < ~/.ssh/id_ed25519.pub + + # Windows (PowerShell) + Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard + ``` + + Or print it and copy manually: + + ```bash + cat ~/.ssh/id_ed25519.pub + ``` + +2. Open GitHub in a browser and sign in with your **personal account** (see + [Wrong account is authenticated](#wrong-account-is-authenticated) if you are unsure). + +3. Navigate to **Settings → SSH and GPG keys**: + + ``` + https://github.com/settings/keys + ``` + + + + +4. Click **New SSH key**. + + + + +5. Fill in the form: + + | Field | Value | + |---|---| + | **Title** | A descriptive name, e.g. `Work MacBook 2025` | + | **Key type** | `Authentication Key` (default) | + | **Key** | Paste the entire contents of `id_ed25519.pub` | + + + + +6. Click **Add SSH key** and confirm with your GitHub password or passkey if prompted. + +7. The key should now appear in the list under **Authentication keys**. + + + + +--- + +## Step 3 — Verify the SSH Connection + +Run the following command to test that GitHub accepts your key: + +```bash +ssh -T git@github.com +``` + +Expected success output: + +``` +Hi ! You've successfully authenticated, but GitHub does not provide shell access. +``` + +The username shown in `Hi !` confirms **which GitHub account** the key is +linked to. If the wrong username appears, see +[Wrong account is authenticated](#wrong-account-is-authenticated). + +You can also use the helper script included in this repository: + +```bash +bash scripts/check-ssh.sh +``` + +--- + +## Step 4 — Configure Git to Use SSH + +If you cloned the repository over HTTPS, switch the remote to SSH: + +```bash +# Check current remote URL +git remote -v + +# Switch to SSH +git remote set-url origin git@github.com:deilert00/Goald.git +``` + +For new clones, always use the SSH URL: + +```bash +git clone git@github.com:deilert00/Goald.git +``` + +--- + +## PAT Fallback (HTTPS Authentication) + +If SSH is blocked by a corporate firewall or you prefer HTTPS, use a Personal Access Token +(PAT) as your password. + +### Generate a PAT + +1. Go to **Settings → Developer settings → Personal access tokens → Tokens (classic)**: + + ``` + https://github.com/settings/tokens + ``` + +2. Click **Generate new token (classic)**. + +3. Set an expiry and select the scopes you need. + For repository operations, `repo` is sufficient. + +4. Click **Generate token** and copy the value immediately — it is shown only once. + + + + +### Use the PAT with Git + +When Git prompts for a password over HTTPS, enter the PAT instead of your account password. + +To avoid re-entering it every time, configure the credential helper: + +```bash +# macOS — store in Keychain +git config --global credential.helper osxkeychain + +# Linux — cache in memory for 1 hour +git config --global credential.helper 'cache --timeout=3600' + +# Windows — Git Credential Manager +git config --global credential.helper manager +``` + +After the next authenticated operation, the token is stored and reused automatically. + +--- + +## Troubleshooting + +### Settings shows an empty SSH key list + +**Symptom:** `https://github.com/settings/keys` shows _"There are no SSH keys associated +with your account."_ + +**Common causes and fixes:** + +| Cause | Fix | +|---|---| +| You are viewing an organization's settings, not your personal account | Go to your personal profile → Settings → SSH and GPG keys (URL: `https://github.com/settings/keys`) | +| You are signed in as the wrong GitHub account | Sign out, sign in as the correct user, then revisit the page | +| You added the key to a different account | Repeat [Step 2](#step-2--add-the-public-key-to-github) while signed in to the correct account | +| Browser cached an old session | Open the settings page in a private/incognito window to confirm the active account | + +To confirm which account is currently signed in, look at the avatar in the top-right corner +of any GitHub page, or check the URL after clicking your avatar: + +``` +https://github.com/ +``` + + + + +--- + +### Permission denied (publickey) + +**Symptom:** + +``` +git@github.com: Permission denied (publickey). +fatal: Could not read from remote repository. +``` + +**Steps:** + +1. Confirm the SSH agent has your key loaded: + + ```bash + ssh-add -l + ``` + + If output is `The agent has no identities.`, add the key: + + ```bash + ssh-add ~/.ssh/id_ed25519 + ``` + +2. Re-test the connection: + + ```bash + ssh -T git@github.com + ``` + +3. Verify the public key appears in your GitHub Settings → SSH and GPG keys page. + +4. If you have multiple SSH keys, ensure `~/.ssh/config` routes `github.com` to the right one: + + ``` + Host github.com + HostName github.com + User git + IdentityFile ~/.ssh/id_ed25519 + ``` + +--- + +### Wrong account is authenticated + +**Symptom:** `ssh -T git@github.com` responds with a different username than expected. + +**Cause:** The SSH agent, or `~/.ssh/config`, is using a key registered to a different +GitHub account. + +**Fix:** + +1. List loaded keys and their associated GitHub accounts: + + ```bash + ssh-add -l + ``` + +2. Remove all identities from the agent: + + ```bash + ssh-add -D + ``` + +3. Add the correct key: + + ```bash + ssh-add ~/.ssh/id_ed25519 + ``` + +4. Verify the correct account responds: + + ```bash + ssh -T git@github.com + # Hi correct-username! You've successfully authenticated... + ``` + +If you manage keys for multiple GitHub accounts on the same machine, use separate key files +and route each hostname alias in `~/.ssh/config`: + +``` +# Personal account +Host github-personal + HostName github.com + User git + IdentityFile ~/.ssh/id_ed25519_personal + +# Work account +Host github-work + HostName github.com + User git + IdentityFile ~/.ssh/id_ed25519_work +``` + +Then use the alias as the host when cloning or setting remotes: + +```bash +git clone git@github-personal:deilert00/Goald.git +``` + +--- + +### Organization SSO restrictions + +**Symptom:** SSH key is listed in your account but `git push` returns: + +``` +ERROR: The `deilert00` organization has enabled or enforced SAML SSO. +To access this repository, visit https://github.com/orgs/deilert00/sso +and authorize your SSH key. +``` + +**Fix:** + +1. Go to `https://github.com/settings/keys`. +2. Find the key you want to use with the organization. +3. Click **Configure SSO** next to the key. +4. Click **Authorize** next to the organization name. + + + + +5. Retry your `git push`. + +--- + +## Quick Reference + +```bash +# Generate key +ssh-keygen -t ed25519 -C "you@example.com" + +# Copy public key (macOS) +pbcopy < ~/.ssh/id_ed25519.pub + +# Test connection (shows active GitHub username) +ssh -T git@github.com + +# Check which keys are loaded +ssh-add -l + +# Switch existing clone from HTTPS to SSH +git remote set-url origin git@github.com:deilert00/Goald.git + +# Run the repo helper script +bash scripts/check-ssh.sh +``` diff --git a/scripts/check-ssh.sh b/scripts/check-ssh.sh new file mode 100755 index 0000000..cb0eebe --- /dev/null +++ b/scripts/check-ssh.sh @@ -0,0 +1,115 @@ +#!/usr/bin/env bash +# scripts/check-ssh.sh +# +# Verifies that SSH authentication to GitHub is working and reports which +# account is active. Also checks whether the current repository remote +# uses SSH or HTTPS and offers to switch. +# +# Usage: +# bash scripts/check-ssh.sh +# +# Exit codes: +# 0 SSH authentication successful +# 1 SSH authentication failed or prerequisite missing + +set -euo pipefail + +# ── colour helpers ──────────────────────────────────────────────────────────── +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +CYAN='\033[0;36m' +BOLD='\033[1m' +RESET='\033[0m' + +ok() { echo -e "${GREEN}✔${RESET} $*"; } +warn() { echo -e "${YELLOW}⚠${RESET} $*"; } +err() { echo -e "${RED}✖${RESET} $*"; } +info() { echo -e "${CYAN}ℹ${RESET} $*"; } +header() { echo -e "\n${BOLD}$*${RESET}"; } + +# ── 1. Check prerequisites ──────────────────────────────────────────────────── +header "1. Checking prerequisites" + +if ! command -v ssh &>/dev/null; then + err "ssh not found. Install OpenSSH and re-run." + exit 1 +fi +ok "ssh is installed ($(ssh -V 2>&1 | head -1))" + +if ! command -v git &>/dev/null; then + err "git not found. Install Git and re-run." + exit 1 +fi +ok "git is installed ($(git --version))" + +# ── 2. Check loaded SSH keys ────────────────────────────────────────────────── +header "2. Loaded SSH keys" + +if ! ssh-add -l &>/dev/null; then + warn "No identities loaded in the SSH agent." + info "Add your key with: ssh-add ~/.ssh/id_ed25519" + info "(If the agent is not running: eval \"\$(ssh-agent -s)\" then ssh-add)" +else + ssh-add -l | while IFS= read -r line; do + ok "$line" + done +fi + +# ── 3. Test SSH connection to GitHub ───────────────────────────────────────── +header "3. Testing SSH connection to GitHub" + +# ssh -T exits with code 1 even on success ("no shell access"), so we capture +# the output and check the content instead. +SSH_OUTPUT=$(ssh -T git@github.com 2>&1) || true + +if echo "$SSH_OUTPUT" | grep -q "successfully authenticated"; then + GITHUB_USER=$(echo "$SSH_OUTPUT" | sed -n 's/Hi \([^!]*\)!.*/\1/p') + ok "Authenticated to GitHub as: ${BOLD}${GITHUB_USER}${RESET}" + echo "" + info "Verify this is the account you expect." + info "If the wrong user appears, see docs/SSH_GITHUB_SETUP.md → 'Wrong account is authenticated'." +else + err "SSH authentication to GitHub failed." + echo "" + echo " Output: ${SSH_OUTPUT}" + echo "" + info "Steps to fix:" + info " 1. Make sure your public key is added to github.com/settings/keys" + info " 2. Add your key to the agent: ssh-add ~/.ssh/id_ed25519" + info " 3. For detailed guidance: docs/SSH_GITHUB_SETUP.md" + exit 1 +fi + +# ── 4. Check remote URL for this repo ──────────────────────────────────────── +header "4. Checking repository remote URL" + +REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true) + +if [[ -z "$REPO_ROOT" ]]; then + warn "Not inside a Git repository — skipping remote URL check." +else + REMOTE_URL=$(git -C "$REPO_ROOT" remote get-url origin 2>/dev/null || echo "") + + if [[ -z "$REMOTE_URL" ]]; then + warn "No 'origin' remote configured." + elif echo "$REMOTE_URL" | grep -q "^git@"; then + ok "Remote 'origin' is already using SSH: ${REMOTE_URL}" + elif echo "$REMOTE_URL" | grep -q "^https://"; then + warn "Remote 'origin' is using HTTPS: ${REMOTE_URL}" + echo "" + info "Switch to SSH with:" + # Derive SSH URL from HTTPS URL (handles github.com/org/repo.git patterns) + SSH_EQUIVALENT=$(echo "$REMOTE_URL" \ + | sed 's|https://github.com/|git@github.com:|') + info " git remote set-url origin ${SSH_EQUIVALENT}" + else + info "Remote 'origin' URL: ${REMOTE_URL}" + fi +fi + +# ── 5. Summary ──────────────────────────────────────────────────────────────── +header "5. Summary" +ok "SSH setup looks good." +info "For full setup instructions and troubleshooting, see:" +info " docs/SSH_GITHUB_SETUP.md"