From 3d5bb3177360f8125acd4a99b8d4f5ae888f2abd Mon Sep 17 00:00:00 2001
From: "Ben Houston (via MyCoder)" <neuralsoft@gmail.com>
Date: Sat, 22 Mar 2025 11:48:37 +0000
Subject: [PATCH] docs: add SSH passphrase best practices to GitHub
 documentation

---
 packages/docs/docs/usage/github-action.md | 12 +++++++++
 packages/docs/docs/usage/github-mode.md   | 32 +++++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/packages/docs/docs/usage/github-action.md b/packages/docs/docs/usage/github-action.md
index 14348db..1aa4d0a 100644
--- a/packages/docs/docs/usage/github-action.md
+++ b/packages/docs/docs/usage/github-action.md
@@ -158,6 +158,18 @@ Configure Git with appropriate user information for commits made by MyCoder:
 
 This clearly identifies commits made automatically by MyCoder.
 
+### SSH Authentication
+
+When using GitHub Actions with SSH authentication:
+
+1. **Avoid SSH Keys with Passphrases**: For automated environments like GitHub Actions, use SSH keys without passphrases or use alternative authentication methods.
+
+2. **Use HTTPS with PAT**: Consider using HTTPS authentication with a Personal Access Token (PAT) for GitHub Actions to avoid SSH passphrase prompts.
+
+3. **If SSH is Required**: If you must use SSH authentication in GitHub Actions, ensure your workflow doesn't require interactive passphrase entry by:
+   - Using SSH keys without passphrases for automation purposes only
+   - Configuring the SSH agent properly in your workflow
+
 ## Usage Examples
 
 ### Trigger MyCoder on an Issue
diff --git a/packages/docs/docs/usage/github-mode.md b/packages/docs/docs/usage/github-mode.md
index 8be6054..84a0775 100644
--- a/packages/docs/docs/usage/github-mode.md
+++ b/packages/docs/docs/usage/github-mode.md
@@ -138,6 +138,38 @@ If your team uses a complex GitHub workflow (e.g., with code owners, required re
 - **Authentication Problems**: Ensure you've run `gh auth login` successfully
 - **Permission Issues**: Verify you have write access to the repository
 - **Branch Protection**: Some repositories have branch protection rules that may prevent direct pushes
+- **SSH Passphrase Prompts**: If you use SSH keys with passphrases, automated workflows may be interrupted by passphrase prompts
+
+### SSH Passphrase Best Practices
+
+When using GitHub mode with SSH authentication, it's important to properly manage SSH key passphrases to ensure automation works smoothly:
+
+1. **Use SSH Agent**: Configure ssh-agent to remember your passphrase, so you don't need to enter it repeatedly:
+
+   ```bash
+   # Start the ssh-agent in the background
+   eval "$(ssh-agent -s)"
+   
+   # Add your SSH private key to the ssh-agent
+   ssh-add ~/.ssh/id_ed25519  # Replace with your key path
+   ```
+
+2. **Configure SSH Agent to Persist**:
+   - On macOS, you can use the keychain to remember your passphrase:
+     ```bash
+     ssh-add --apple-use-keychain ~/.ssh/id_ed25519
+     ```
+   - On other systems, consider using tools like `keychain` or configuring your desktop environment to start ssh-agent automatically
+
+3. **Create Config File** (optional): Create or edit `~/.ssh/config` to use the ssh-agent:
+   ```
+   Host github.com
+     AddKeysToAgent yes
+     UseKeychain yes  # macOS only
+     IdentityFile ~/.ssh/id_ed25519
+   ```
+
+Without proper SSH agent configuration, MyCoder may be interrupted by passphrase prompts during Git operations, which can cause timeouts in automated environments.
 
 If you encounter any issues with GitHub mode, you can check the GitHub CLI status with: