setup SSH key for git repo

[OleksandrKucherenko]

Checks

• I have searched the existing issues.

Motivation

Overview:

• common situation when we have multiple accounts: company, personal, provided.

Problem:

• setup which SSH key git repo should use for pushing the changes in easy way

Solution:

• setup multiple SSH keys
• re-configure git repo core.sshCommand and git remote so git start to use a correct SSH key for common operations

# different approaches
git config --global core.sshCommand "ssh -i /path/to/key"
git config --local core.sshCommand "ssh -i /path/to/key"
git submodule foreach git config core.sshCommand "ssh -i /path/to/key"
git config core.sshCommand "ssh -o IdentityAgent=none -i $HOME/.ssh/id_rsa_example -F /dev/null" 

# or setup GIT_SSH_COMMAND env variable

References:

• https://blog.prag.dev/telling-git-how-to-use-ssh-nicely
• https://stackoverflow.com/questions/57657130/how-to-propagate-the-core-sshcommand-option-to-submodule-update
• https://docs.github.com/en/authentication/connecting-to-github-with-ssh
• https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables
• https://superuser.com/questions/232373/how-to-tell-git-which-private-key-to-use

Implementation

1. If lazyssh executed from git repo folder, we should ask user does he/she needs to reconfigure git repo SSH key or not
2. support keychain (https://github.com/danielrobbins/keychain) for automatic loading of SSH keys (ref: https://www.funtoo.org/Funtoo:Keychain)

Are you willing & able to help?

• I am able to submit a PR!
• I can help test the feature!

[OleksandrKucherenko]

🚀 Feature Requirements: Git Repo SSH Key Selection & Configuration

(support for configuring git repo core.sshCommand and SSH key handling)

1. 🎯 Feature Summary

Users frequently work with multiple Git identities (company, personal, vendor-provided). Git provides several mechanisms to control which SSH key is used for operations, but switching between keys—especially on a per-repository level—is error-prone and non-discoverable.

Goal:
Extend lazyssh with a guided workflow that allows users to select, add, activate, and apply an SSH key to a Git repository by configuring core.sshCommand or environment variables (GIT_SSH_COMMAND) automatically.

---

2. 🧠 Deep Technical & Functional Clarification

2.1 Scope of Feature

This feature introduces:

A. Git Repository Detection

• When lazyssh is executed inside a Git repository (.git folder detected):

  • Ask the user whether they want to configure SSH for Git operations.
  • Provide options to view, set, or clear SSH configuration.

B. Manage SSH Keys for Git Remote Access

We support 3 key-handling approaches:

1. Per-repository config:
   git config core.sshCommand "ssh -i /path/to/key"

2. Global override:
   git config --global core.sshCommand "ssh -i /path/to/key"

3. Environment-level override:
   Export GIT_SSH_COMMAND="ssh -i /path/to/key"

4. (Optional) Submodule support:
   git submodule foreach git config core.sshCommand "ssh -i /path/to/key"

5. Keychain integration (Funtoo Keychain):

   • Detect presence of keychain
   • Load keys automatically via:
     keychain --eval ~/.ssh/<private_key>

---

2.2 What Must Be Modified / Added Internally

1. Git Context Detection

Implement a utility:
is_git_repo(cwd) → boolean

2. Git SSH Configuration Manager

Create a new module:

lazyssh/git_ssh_manager.py

Responsibilities:

• List current Git SSH config (local/global)
• Detect if a repo is using core.sshCommand
• Apply new SSH configuration
• Reset repo configuration
• Validate remote URLs (git@github.com:…, ssh://…)

3. SSH Key Registry

Extend existing key-handling logic:

• Enumerate keys in ~/.ssh
• Validate readable private key files
• Mark keys “loaded by keychain” if active

4. User Interaction (UI/CLI)

Add a new dialog-driven workflow:

lazyssh git-setup

Triggered automatically when running inside a Git repo unless suppressed by a flag.

5. Keychain Support

Implement detection:

if command_exists("keychain"):
    # ask user if keychain should be configured

6. Configuration Persistence

Store optional metadata:

• Last used key per repo (via .lazyssh.yml inside repo or ~/.config/lazyssh)

---

3. 🧩 UX / UI Specification

3.1 When LazySSH Starts in a Git Repo

Detected Git repository.
Would you like to configure which SSH key Git should use?

[1] Yes – configure Git SSH key
[2] No – continue without changes

3.2 Key Selection Screen

Select SSH key to use for this repository:

[1] id_rsa_personal
[2] id_ed25519_work
[3] id_rsa_vendor
[4] Add new key

If user chooses Add new key:

Show path prompt + validation.

---

3.3 Choose Configuration Method

How should Git use this key?

[1] Set repo-only SSH command (recommended)
    git config core.sshCommand "ssh -i …"
[2] Set global Git SSH command
[3] Use environment variable GIT_SSH_COMMAND
[4] Configure for all submodules too

---

3.4 Final Confirmation

Show what will be executed:

The following Git configuration will be applied:

git config core.sshCommand "ssh -o IdentityAgent=none -i ~/.ssh/id_ed25519_work -F /dev/null"

Proceed?
[y] Yes   [n] Cancel

---

3.5 Keychain Support Prompt

If keychain installed:

Keychain detected. Load this key automatically using keychain?

keychain --eval ~/.ssh/id_ed25519_work

---

4. 📐 Detailed Behavior Rules

4.1 Repository-Level Configuration Takes Priority

Git searches in this order:

1. core.sshCommand (local)
2. core.sshCommand (global)
3. GIT_SSH_COMMAND env variable
4. SSH config (~/.ssh/config)

We must display current priority chain clearly to the user.

---

4.2 Submodule Propagation

If repo has .gitmodules:

• Ask user whether submodules should inherit the sshCommand
• Run:

git submodule foreach \
   git config core.sshCommand "ssh -i /path/to/key"

---

4.3 Clearing Configuration

Provide option:

Reset SSH configuration for this repo?

[1] Remove core.sshCommand
[2] Remove global core.sshCommand
[3] Remove both

---

5. 🧪 Testing Requirements

5.1 Testing Scenarios

Scenario A: Running lazyssh inside Git repo

Expected:

• Detect git repo
• Trigger config prompt
• Allow selecting an SSH key

Scenario B: Selecting a key and applying repo-level config

Expected:

• git config core.sshCommand updated
• Key validation performed
• User sees summary

Scenario C: Repo with existing sshCommand

Expected:

• Detect existing config
• Ask whether to overwrite it

Scenario D: Submodule propagation

Expected:

• Submodules receive identical config
• Show per-submodule status report

Scenario E: Keychain installed

Expected:

• Prompt user
• keychain commands executed correctly

Scenario F: Invalid key path

Expected:

• Meaningful error displayed
• User returned to key selection

---

6. 🧪 Unit Test Cases (Given / When / Then)

1. Git Repo Detection

Given: cwd contains .git/
When: is_git_repo() is called
Then: returns True

Given: no .git/ present
Then: returns False

---

2. Local SSH Command Configuration

Given: a valid SSH key path
When: user selects repo-level configuration
Then: git config core.sshCommand equals expected value

---

3. Overwrite Existing Config

Given: core.sshCommand already set
When: user chooses to overwrite
Then: previous value replaced

---

4. Submodule Handling

Given: repo contains submodules
When: user enables propagation
Then: each submodule directory contains the same config

---

5. Keychain Integration

Given: keychain installed
When: user selects “load via keychain”
Then: tool runs keychain --eval <key> and stores output

---

6. Invalid SSH Key Handling

Given: an unreadable file path
When: user selects that path
Then: error shown + re-prompted for new key

[OleksandrKucherenko]

🎨 LazySSH-Compatible ASCII UI Mockups

Git SSH Key Configuration Flow (Designed to fit LazySSH existing screens)

---

1️⃣ Mockup: Git Repo Detected (Top Banner Stays the Same)

┌──────────────────────────────────────────────────────────────────────────────┐
│ lazyssh                                             v0.0.x      Git Setup    │
│ Press / to search…   ↑↓ Navigate   Enter Select   q Quit                     │
├──────────────────────────────────────────────────────────────────────────────┤
│ Git Repository Detected                                                      │
│                                                                              │
│ Path: /home/user/projects/my-repo                                            │
│                                                                              │
│ This folder is a Git repository. Would you like to configure which SSH key   │
│ Git should use for operations (clone, pull, push)?                           │
│                                                                              │
│   [1] Configure SSH key for this Git repo                                    │
│   [2] Skip (do nothing)                                                      │
└──────────────────────────────────────────────────────────────────────────────┘

---

2️⃣ Mockup: SSH Key Selection (Left = List, Right = Details)

┌──────────────────────────────────────────────────────────────────────────────┐
│ lazyssh                                         Git SSH Key Selection        │
│ ↑↓ Navigate   Enter Select   a Add   q Back                                  │
├──────────────────────────────────────────────────────────────────────────────┤
│ SSH Keys (from ~/.ssh/)                             Details                  │
│───────────────────────────────────────┬──────────────────────────────────────│
│  id_ed25519_work                      │ Key: id_ed25519_work                 │
│  id_rsa_personal                      │ Path: ~/.ssh/id_ed25519_work         │
│  id_ed25519_vendor                    │ Size: 4096 bits                      │
│  id_github_custom                     │ Loaded: yes (via ssh-agent)          │
│                                       │                                      │
│  + Add new SSH key…                   │ Press Enter to select this key       │
│                                       │                                      │
│                                       │                                      │
└───────────────────────────────────────┴──────────────────────────────────────┘

---

3️⃣ Mockup: Add New Key Path Prompt (Centered Dialog)

┌──────────────────────────────────────────────────────────────────────────────┐
│ lazyssh                                                          Add SSH Key │
├──────────────────────────────────────────────────────────────────────────────┤
│ Enter full path to private SSH key:                                          │
│                                                                              │
│   ~/.ssh/                                                                    │
│   > _                                                                        │
│                                                                              │
│ Press Enter to continue, or ESC to cancel.                                   │
└──────────────────────────────────────────────────────────────────────────────┘

Validation Error Popup (Inline Modal)

┌───────────────────────────────┐
│ Invalid SSH key file!         │
│ The file is not readable or   │
│ is not a private key.         │
│                               │
│ Press any key to continue…    │
└───────────────────────────────┘

---

4️⃣ Mockup: Git SSH Configuration Options

┌──────────────────────────────────────────────────────────────────────────────┐
│ lazyssh                                                   Git Configuration  │
│ ↑↓ Navigate   Enter Select   q Back                                          │
├──────────────────────────────────────────────────────────────────────────────┤
│ Configure how Git should use the selected SSH key:                           │
│                                                                              │
│ [1] Set repo-only SSH command (recommended)                                  │
│       git config core.sshCommand "ssh -i ~/.ssh/id_ed25519_work"             │
│                                                                              │
│ [2] Set global Git SSH command                                               │
│ [3] Use GIT_SSH_COMMAND env variable                                         │
│ [4] Apply same settings to submodules (if present)                           │
│                                                                              │
│ [5] Cancel                                                                   │
└──────────────────────────────────────────────────────────────────────────────┘

---

5️⃣ Mockup: Submodule Propagation Screen

┌──────────────────────────────────────────────────────────────────────────────┐
│ lazyssh                                               Submodule Settings     │
├──────────────────────────────────────────────────────────────────────────────┤
│ This repository contains Git submodules.                                     │
│                                                                              │
│ Apply SSH configuration to all submodules as well?                           │
│                                                                              │
│   [1] Yes – configure all submodules                                         │
│   [2] No – configure main repository only                                    │
└──────────────────────────────────────────────────────────────────────────────┘

---

6️⃣ Mockup: Keychain Integration Screen

┌──────────────────────────────────────────────────────────────────────────────┐
│ lazyssh                                               Keychain Integration   │
├──────────────────────────────────────────────────────────────────────────────┤
│ Keychain utility detected: /usr/bin/keychain                                 │
│                                                                              │
│ Load selected key automatically using keychain?                              │
│                                                                              │
│   keychain --eval ~/.ssh/id_ed25519_work                                     │
│                                                                              │
│   [1] Yes – integrate with keychain                                          │
│   [2] No – skip                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

---

7️⃣ Mockup: Final Confirmation

┌──────────────────────────────────────────────────────────────────────────────┐
│ lazyssh                                      Review Git SSH Configuration    │
├──────────────────────────────────────────────────────────────────────────────┤
│ Git configuration to be applied:                                             │
│                                                                              │
│   git config core.sshCommand "ssh -o IdentityAgent=none                      │
│                                      -i ~/.ssh/id_ed25519_work -F /dev/null" │
│                                                                              │
│ Proceed?                                                                     │
│                                                                              │
│  [Y] Yes   [N] No                                                            │
└──────────────────────────────────────────────────────────────────────────────┘

---

8️⃣ Mockup: Success Screen (Matches LazySSH Style)

┌──────────────────────────────────────────────────────────────────────────────┐
│ lazyssh                                                   Success            │
├──────────────────────────────────────────────────────────────────────────────┤
│ Git SSH key configuration applied successfully!                              │
│                                                                              │
│ Git will now use: ~/.ssh/id_ed25519_work                                     │
│ for all SSH operations in this repository.                                   │
│                                                                              │
│ Press any key to return to main screen…                                      │
└──────────────────────────────────────────────────────────────────────────────┘

[OleksandrKucherenko]

p.s. will be great to provide this with DIRENV (https://direnv.net/) and MISE (https://mise.jdx.dev/) integration