Forgejo SSH Key Setup Script

A robust script that automates the process of creating and configuring SSH keys for Forgejo. This script provides a user-friendly interface for generating ED25519 SSH keys, configuring SSH settings, and verifying the connection with your Forgejo instance.

PowerShell Version (Windows)

Prerequisites

• PowerShell 7 or later
• OpenSSH client installed
• Forgejo instance running

Usage

1. Run the script:

.\forgejo-ssh-key-setup.ps1

2. Follow the prompts:
   • Enter your email address
   • Create a passphrase (optional but recommended)
   • Copy the public key when displayed
   • Add the key to Forgejo
   • Verify the key using the challenge token

SSH Key Location

The script creates these files:

C:\Users\{user}\.ssh\id_ed25519     # Private key
C:\Users\{user}\.ssh\id_ed25519.pub # Public key

Shell Script Version (Unix/Linux/macOS/WSL)

Prerequisites

• Unix-like operating system (Linux, macOS, WSL)
• OpenSSH client installed
• sh shell (POSIX-compliant)
• Forgejo instance running

Usage

1. Make the script executable:

chmod +x forgejo-ssh-key-setup.sh

2. Run the script:

./forgejo-ssh-key-setup.sh

3. Follow the interactive prompts:
   • Enter your Forgejo location (e.g., forgejo.example.com or 192.168.1.100:3000)
   • Enter your email address
   • Create a passphrase (optional but recommended)
   • Copy the public key when displayed
   • Add the key to Forgejo
   • Verify the key using the challenge token

SSH Key Location

The script creates these files in your home directory:

~/.ssh/id_ed25519     # Private key
~/.ssh/id_ed25519.pub # Public key

Features

• Generates ED25519 SSH key pair
• Validates email format
• Adds key to SSH agent
• Configures SSH config file with robust duplicate entry handling
• Verifies key with Forgejo using challenge-response
• Tests SSH connection with proper exit code handling
• Comprehensive error handling and troubleshooting
• Colorized output for better readability
• Support for custom Forgejo locations (including ports)

SSH Config

The script can optionally configure your SSH config file with these settings:

Host your-forgejo-host
    HostName your-forgejo-host
    User your-username
    IdentityFile ~/.ssh/id_ed25519
    PreferredAuthentications publickey
    PubkeyAuthentication yes
    PasswordAuthentication no

Forgejo Setup

1. Login to your Forgejo web server
2. Click on your profile avatar (top right corner)
3. Select "Settings"
4. In the left sidebar, click on "SSH / GPG Keys"
5. Click the "Add Key" button
6. Give your key a descriptive "Title" (e.g., "My Laptop Key")
7. Paste the entire public key into the "Content" text area
8. Click "Add Key"
9. After adding, click the "Verify" button next to your new key
10. Copy the challenge token provided by Forgejo
11. Run the verification command in your terminal

Troubleshooting

PowerShell Version

If you encounter issues:

1. Check that your SSH key is properly added to your Forgejo account
2. Verify the key fingerprint matches
3. Ensure your SSH config is correct
4. Check the connection with verbose output: ssh -v -p 222 git@your-forgejo-server

Shell Script Version

If you encounter issues:

1. Key Verification Fails:

   • Make sure you copied the ENTIRE signature block
   • Check for extra spaces or line breaks
   • Verify the token was entered correctly
   • Get a fresh token if the current one expired

2. SSH Connection Fails:

   • Check that your SSH key is properly added to your Forgejo account
   • Verify the key fingerprint matches
   • Ensure your SSH config is correct
   • Check the connection with verbose output: ssh -v -T git@your-forgejo-server

3. SSH Agent Issues:

   • Start the SSH agent manually: eval $(ssh-agent -s)
   • Add your key manually: ssh-add ~/.ssh/id_ed25519

Exit Codes

The script uses these exit codes:

• 0: Success
• 1: General error or connection test failure
• Other codes: SSH-specific errors

License

This project is open source and available under the MIT License.