Use A GitHub SSH Key For Lab Projects

Goal: use a personal SSH key for Git clones, pulls and pushes, and avoid retyping its passphrase for every operation. SSH authenticates Git; gh uses its separate saved login for GitHub API operations such as PRs and checks. HTTPS with gh also keeps credentials: repeated password prompts need troubleshooting, not repeated login or passwords pasted into an agent.

Before starting: finish the Git lessons, use your intended GitHub account, and have Git and OpenSSH on this computer. Keep the Passport transport and practice remotes unchanged; preparation checks their HTTPS origin. This guide is for lab project clones and does not change your Passport grade.

Where: PowerShell on your Windows computer; Terminal with zsh on macOS or Bash on Linux. For GitHub on Euler, use the separate code-sync procedure; create a key there rather than copying your computer's private key or forwarding its SSH agent.

If opening a terminal or running a command is new, use Terminal and command basics first.

1. Create Or Reuse The Named Key#

The public .pub file goes to GitHub; the private file stays on this machine. Use a passphrase when generating it. This protects the private key; it is not your GitHub password. Never send either password or the private file to an agent. The blocks keep an existing complete key pair and stop on incomplete files. If you already use another working GitHub key, keep it and follow the official existing-key instructions instead of generating or replacing it blindly.

Expected: a new pair is created after your passphrase prompts, or existing-key-kept. Do not overwrite an existing key to fix authentication.

Windows: PowerShell#

& {
  $Key = Join-Path $env:USERPROFILE ".ssh\id_ed25519_github"
  $Keygen = Join-Path $env:WINDIR "System32\OpenSSH\ssh-keygen.exe"
  if (-not (Test-Path -LiteralPath $Keygen)) { throw "STOP: Windows OpenSSH is missing" }
  if ((Test-Path -LiteralPath $Key) -or (Test-Path -LiteralPath "$Key.pub")) {
    if (-not ((Test-Path -LiteralPath $Key -PathType Leaf) -and (Test-Path -LiteralPath "$Key.pub" -PathType Leaf))) { throw "STOP: incomplete key pair; preserve it and ask for help" }
    Write-Output "existing-key-kept"
  } else {
    New-Item -ItemType Directory -Force -Path (Split-Path -Parent $Key) | Out-Null
    & $Keygen -t ed25519 -C "GitHub on this computer" -f $Key
    if ($LASTEXITCODE -ne 0) { throw "STOP: key creation failed" }
  }
}

macOS Or Linux: Terminal#

(
  key="$HOME/.ssh/id_ed25519_github"
  if [ -e "$key" ] || [ -e "$key.pub" ] || [ -L "$key" ] || [ -L "$key.pub" ]; then
    [ -f "$key" ] && [ -f "$key.pub" ] || { printf 'STOP: incomplete key pair; preserve it and ask for help\n' >&2; exit 1; }
    printf 'existing-key-kept\n'
  else
    umask 077
    mkdir -p "$HOME/.ssh" || exit 1
    ssh-keygen -t ed25519 -C "GitHub on this computer" -f "$key"
  fi
)

2. Add Only The Public Key To GitHub#

Open GitHub SSH keys under the same account as your Passport. Choose New SSH key, an Authentication Key, and a machine label you will recognize. Copy the whole public-key line below into its Key field, then save it. Only the file ending in .pub is printed.

Expected: a line beginning with ssh-ed25519, and the key listed in the intended account. Adding a key does not grant access to a private lab repository.

Windows: PowerShell#

Get-Content -LiteralPath (Join-Path $env:USERPROFILE ".ssh\id_ed25519_github.pub")

macOS Or Linux: Terminal#

cat "$HOME/.ssh/id_ed25519_github.pub"

3. Let The SSH Agent Remember The Passphrase#

An SSH agent holds an unlocked key for your session. Add it yourself; do not remove its passphrase or let a coding agent handle it. After a restart or an agent timeout, you may need to add it again.

Expected: Identity added after your passphrase. It may be requested once when unlocking the key, rather than at every Git operation.

Windows: PowerShell#

Use Windows OpenSSH for both ssh-add and Git; Git for Windows can otherwise use a different SSH program that cannot talk to the Windows agent.

Get-Service -Name ssh-agent

If it is Running, use your ordinary PowerShell terminal:

& (Join-Path $env:WINDIR "System32\OpenSSH\ssh-add.exe") (Join-Path $env:USERPROFILE ".ssh\id_ed25519_github")

If the Windows ssh-agent service is stopped

On your own computer, open an administrator PowerShell and enable only this service, then close that administrator terminal. On a managed lab computer, ask IT before changing a service.

Set-Service -Name ssh-agent -StartupType Automatic
Start-Service -Name ssh-agent

Return to ordinary PowerShell and run the ssh-add command above. Do not run Git or your coding agent as administrator.

macOS: Terminal#

/usr/bin/ssh-add --apple-use-keychain "$HOME/.ssh/id_ed25519_github"

This uses Apple's SSH agent/keychain support. The project clone command below also selects Apple's SSH client.

Linux: Terminal#

ssh-add "$HOME/.ssh/id_ed25519_github"

If Linux says it cannot connect to an authentication agent

Start an agent for this terminal, then add the key. Keep using this terminal; the commands do not edit your shell startup files. Run a command-line coding agent from this same terminal. An already running editor does not inherit a new SSH agent socket: fully quit it, then launch it from this terminal before using its agent.

eval "$(ssh-agent -s)"
ssh-add "$HOME/.ssh/id_ed25519_github"

4. Verify The GitHub Account#

Windows: PowerShell#

& (Join-Path $env:WINDIR "System32\OpenSSH\ssh.exe") -F none -i (Join-Path $env:USERPROFILE ".ssh\id_ed25519_github") -o IdentitiesOnly=yes -T git@github.com

macOS Or Linux: Terminal#

ssh -F none -i "$HOME/.ssh/id_ed25519_github" -o IdentitiesOnly=yes -T git@github.com

Check The Reply#

On first contact, compare the host fingerprint with GitHub's official fingerprints before accepting. Stop on a changed or mismatched fingerprint.

Expected: Hi YOUR-USERNAME! You've successfully authenticated, but GitHub does not provide shell access. Verify that it names your intended account. GitHub deliberately returns exit code 1 for this successful shell test. Permission denied (publickey) is a failure; do not proceed from that message.

5. Clone The Lab Context#

Reuse an existing onboarding-IT checkout if it is already accessible to your agent. Otherwise run the block for your OS from the folder where you keep lab code, outside the Passport practice folder. It selects the named key and records that selection only in the new clone's local Git configuration. Quoting keeps paths with spaces or apostrophes intact. Existing remotes, global Git settings and SSH configuration are not rewritten.

Windows: PowerShell#

& {
  function Quote-GitShell([string] $Value) { "'" + $Value.Replace("'", "'\''") + "'" }
  $Key = (Join-Path $env:USERPROFILE ".ssh\id_ed25519_github").Replace("\", "/")
  $Ssh = (Join-Path $env:WINDIR "System32\OpenSSH\ssh.exe").Replace("\", "/")
  $GitSsh = (Quote-GitShell $Ssh) + " -F none -i " + (Quote-GitShell $Key) + " -o IdentitiesOnly=yes"
  git -c "core.sshCommand=$GitSsh" clone git@github.com:IDEALLab/onboarding-IT.git
  if ($LASTEXITCODE -ne 0) { throw "STOP: clone failed; existing folders were preserved" }
  git -C onboarding-IT config --local core.sshCommand $GitSsh
  if ($LASTEXITCODE -ne 0) { throw "STOP: local SSH selection failed; preserve the clone" }
}

macOS Or Linux: Terminal#

(
  key="$HOME/.ssh/id_ed25519_github"
  quoted_key=$(printf '%s' "$key" | sed "s/'/'\"'\"'/g")
  ssh_program=ssh
  if [ "$(uname -s)" = Darwin ]; then ssh_program=/usr/bin/ssh; fi
  git_ssh="$ssh_program -F none -i '$quoted_key' -o IdentitiesOnly=yes"
  git -c core.sshCommand="$git_ssh" clone git@github.com:IDEALLab/onboarding-IT.git || exit 1
  git -C onboarding-IT config --local core.sshCommand "$git_ssh"
)

Continue After Cloning#

Expected: an onboarding-IT folder containing the lab briefing and its linked procedures. Then follow Give your agent the lab context. For another authorized lab project, use its GitHub Code > SSH URL in place of the handbook URL and its actual clone folder in the git -C command. Do not change the Passport repositories' URLs.

If Blocked#

Windows OpenSSH missing: ask lab IT to install the Windows OpenSSH client on a managed computer. Keep existing keys; this is a missing program, not a GitHub password failure. Return to step 1 after installation.
Repeated passphrase requests: check that the key was added and that Git uses the same SSH client as the agent. On Windows use the clone block above. Keep the passphrase; do not copy a private key into a prompt or job script.
Wrong username or permission denied: check the account's public-key entry and selected key path. Preserve your keys; do not regenerate every key.
Repository not found: ask the project owner for repository access. If the organization requires SSO, follow GitHub's key authorization procedure.
HTTPS password prompts in the Passport: follow the existing GitHub authentication recovery. Do not replace a working Passport remote merely to remove a prompt.

Verification And AI Review#

You have checked the GitHub account, the clone, and the local SSH selection. Let the agent use the authorized project after you unlock the key; keep reviewing its commands and diff. SSH authentication is not authorization to commit, push, install packages, or submit Euler jobs.

Sources: GitHub CLI login, SSH key generation and agents, public-key registration, SSH test result. Verified: 2026-10-10. Review by: 2027-01-10. Owner: IDEAL Lab IT.