gh-ssh-setup

Generate an SSH key on your machine and add it to GitHub — either with clear, copy-paste steps, or fully automated through the GitHub REST API.

• 🔐 Pure-Python key generation (Ed25519 by default, RSA optional) via cryptography — no external ssh-keygen required.
• 📋 Prints every manual step (ssh-agent, copy public key, add on GitHub, test).
• 🤖 One command to generate + upload + verify, end to end.
• 🛡️ Private key written 0600; only the public key ever leaves your machine.

Install

pip install gh-ssh-setup

From source:

git clone https://github.com/rghosh08/gh-ssh-setup
cd gh-ssh-setup
pip install -e .

Usage

1. Generate a key and see the manual GitHub steps

gh-ssh-setup generate --email you@example.com

This creates ~/.ssh/id_ed25519 + ~/.ssh/id_ed25519.pub and prints the exact steps to register it at https://github.com/settings/ssh/new.

2. Full automation (generate → upload → test)

Create a GitHub Personal Access Token with the admin:public_key (write:public_key) scope at https://github.com/settings/tokens, then:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx
gh-ssh-setup setup --email you@example.com --title "my-laptop"

Output:

✔ Authenticated to GitHub as yourname
✔ Generated ed25519 key
✔ Added key 'my-laptop' to GitHub (id=123456789)
→ Testing: ssh -T git@github.com
  Hi yourname! You've successfully authenticated, but GitHub does not provide shell access.

Other commands

gh-ssh-setup upload --key-path ~/.ssh/id_ed25519.pub --title "existing-key"
gh-ssh-setup list        # show keys already on your GitHub account
gh-ssh-setup test        # run ssh -T git@github.com

Run gh-ssh-setup <command> --help for all flags (--type rsa, --passphrase, --overwrite, --key-path, --no-agent, ...). setup/generate also print an optional ~/.ssh/config block and load the key into ssh-agent for you (skip with --no-agent).

Use as a library

from gh_ssh_setup import generate_key_pair, upload_key_to_github, manual_steps

kp = generate_key_pair(comment="you@example.com")
print(manual_steps(kp))                              # copy-paste steps
upload_key_to_github(kp.public_key, title="laptop")  # or automate it

GitHub MCP (agentic automation)

If you drive this from an agent that has the GitHub MCP server connected, you can skip the token plumbing and let the agent call the equivalent MCP tool to create the key (POST /user/keys). This package still does the key generation locally (the private key must never leave your machine); the MCP only handles the public-key upload. Point your agent at:

• Generate locally: gh-ssh-setup generate (or generate_key_pair()).
• Upload via MCP: call the GitHub MCP "create SSH signing/auth key" tool with the .pub contents, or just use gh-ssh-setup setup with a token.

Security notes

• The private key (id_ed25519) is secret. This tool writes it 0600 and never transmits it. Only the .pub file is uploaded.
• Prefer a short-lived, minimally-scoped PAT (admin:public_key only).
• Consider a --passphrase for defense in depth on shared machines.

Development

A Makefile wraps the common tasks (make help to list them):

make dev      # pip install -e ".[dev]"
make test     # pytest
make build    # sdist + wheel into dist/
make check    # twine check dist/*

CI runs on every push/PR (Python 3.8–3.12). Pushing a vX.Y.Z tag publishes to PyPI automatically via Trusted Publishing — see PUBLISHING.md.

License

MIT — see LICENSE.