Configure a Local Git Workflow with SSH Keys and Hooks on Windows 10/11
Difficulty: Intermediate | Time Required: 25 minutesIntroduction
Git is a powerful version-control system, and using SSH keys for authentication makes pushes and pulls secure and convenient. Coupled with local Git hooks, you can enforce code quality, run tests, and automate checks before every commit or push. This guide walks you through a practical, Windows‑friendly setup for Windows 10/11 that uses SSH keys, an ssh-agent, and simple, customizable Git hooks to keep your workflow smooth and reliable.
Prerequisites
- Windows 10 or Windows 11 PC (any recent build works; you’ll mainly rely on the built‑in OpenSSH client or the Git for Windows package).
- Git for Windows installed (includes Git Bash and SSH tools). If you don’t have it, download from git-scm.com and install with the default options.
- Access to a remote Git repository you’ll use with SSH (e.g., GitHub, GitLab, or a local SSH Git server). You’ll need to add your public key to the remote host.
- Optional but recommended: a small project you’ll clone or initialize to test the workflow.
- Basic familiarity with command-line usage (Git Bash or Windows Terminal with Git in PATH).
- OpenSSH client is available on Windows 10 and 11 as an Optional Feature. You can enable it via Settings > Apps > Optional Features > Add a feature > OpenSSH Client.
- On Windows 11, the OpenSSH client is typically present by default. Git for Windows also provides ssh through Git Bash.
1) Install and verify Git for Windows
- If not already installed, download and install Git for Windows from git-scm.com.
- During installation, keep the default options, which include Git Bash (your command shell) and ssh.
- After installation, open Git Bash and verify:
- git --version
- ssh -V
- Optional: decide whether you want to use Git from Windows Command Prompt too (the installer can add Git to PATH for cmd.exe).
- Open Git Bash (Start > Git Bash).
- Generate a new SSH key pair (ed25519 recommended):
- ssh-keygen -t ed25519 -C "you@example.com"
- When prompted for a file to save the key, press Enter to accept the default location: /c/Users/YourName/.ssh/id_ed25519
- Choose a passphrase for extra security (recommended) or leave blank (less security).
- Confirm the key generation. You should see messages about your public and private keys being created.
- In Git Bash, start the agent:
- eval "$(ssh-agent -s)"
- Add your new key to the agent:
- ssh-add ~/.ssh/id_ed25519
- If you’re on a system that runs ssh-agent automatically, this step may be seamless, but running the commands above ensures your key is loaded for this session.
- Display your public key and copy it:
- cat ~/.ssh/id_ed25519.pub
- On GitHub (or GitLab, Bitbucket, etc.), add the key to your account:
- GitHub: Settings > SSH and GPG keys > New SSH key
- Paste the copied key and save.
- For a private or local SSH server, append your public key to the authorized_keys file on the server (or upload via the server’s UI if supported).
- Test the connection (replace github.com with your host if you’re using another service):
- ssh -T git@github.com
- You should see a welcome message or a note about successful authentication.
- Create or edit the SSH config file at ~/.ssh/config (you can create it in Git Bash):
- nano ~/.ssh/config
- Or use a simple text editor and save as ~/.ssh/config.
- Add host-specific blocks to simplify commands and support multiple keys:
- Host github.com
HostName github.com
User git
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519 - If you have a private server:
Host mygitserver
HostName your.server.local
User git
Port 22
IdentityFile ~/.ssh/id_ed25519
- Host github.com
- Save and close. This lets you use git remote URLs like git@github.com:username/repo.git or git@mygitserver:repo.git without specifying keys each time.
- If you’re starting fresh:
- mkdir -p ~/projects/myproj
- cd ~/projects/myproj
- git init
- If you’re cloning a remote repo:
- git clone git@github.com:username/repo.git
- Set up a remote if you already have a local repo:
- git remote add origin git@github.com:username/repo.git
- Confirm connectivity:
- git ls-remote origin
- Local workflow tip: keep your central repo as the “origin” and create feature branches off main or master.
Hacking a little automation into your local workflow can pay off. Here are two straightforward hooks you can customize for your project.
A. Pre-commit hook: catch trailing whitespace and enforce a simple check
- Create the hook file:
- mkdir -p .git/hooks
- nano .git/hooks/pre-commit
- Example content (bash script):
- Make it executable:
- chmod +x .git/hooks/pre-commit
- What it does: prevents committing files with trailing whitespace in common text/code files. You can tailor the grep pattern to your project.
- Create the hook file:
- nano .git/hooks/pre-push
- Example content (bash script; adjust to your tech stack):
- Make it executable:
- chmod +x .git/hooks/pre-push
- This ensures you don’t push code that doesn’t pass basic tests when a test script exists.
- If you manage many repos, you can consolidate hooks in a central directory and point Git to use them via core.hooksPath.
- Example:
- git config core.hooksPath .githooks
- Create a .githooks/ directory at the project root and place pre-commit, pre-push, etc., inside it.
- On Windows, keep in mind that creating symlinks requires elevated permissions. If that’s a problem, use individual hooks per repo as shown above.
- SSH authentication fails: ensure the agent is running and the key is added. Re-run ssh-add if you’re prompted for the passphrase. Check that the public key is correctly stored on the remote host.
- Command not found: make sure you’re in Git Bash or a terminal that has Git and SSH in PATH. Reopen the terminal after installing Git.
- Line endings causing trouble: set core.autocrlf to input on Windows to avoid converting line endings when pushing to a UNIX-based host:
- git config --global core.autocrlf input
- Permissions on key files: Windows uses a different permissions model, but you should still keep the private key secure. Within Git Bash, you can set:
- chmod 600 ~/.ssh/id_ed25519
- Hooks not running: ensure the scripts are executable (chmod +x) and that you’re editing the correct repo’s .git/hooks directory.
A SSH-based workflow on Windows 10/11 gives you secure, password-less authentication for Git operations and a reliable, automated gatekeeper in the form of hooks. You can start small (SSH keys + a single pre-commit check) and gradually add more hooks to enforce your team’s coding standards. The combination of a clean SSH setup and targeted hooks helps you push fewer bugs to your shared repos, keep your local environment consistent, and save time in the long run.
Key Takeaways:
- SSH keys provide secure, password-free authentication for Git across Windows 10/11.
- SSH agent management ensures your private key stays available for Git without re-entry of passphrases.
- Simple Git hooks (pre-commit and pre-push) give you quick quality gates before changes leave your machine.
- A small SSH config and clear remote URLs make working with multiple hosts easy and error-free.
This tutorial was generated to help WindowsForum.com users get the most out of their Windows experience.
