162 lines
No EOL
4.3 KiB
Markdown
162 lines
No EOL
4.3 KiB
Markdown
# 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.
|
|
|
|
<details>
|
|
<summary><strong>PowerShell Version (Windows)</strong></summary>
|
|
|
|
## Prerequisites
|
|
|
|
- PowerShell 7 or later
|
|
- OpenSSH client installed
|
|
- Forgejo instance running
|
|
|
|
## Usage
|
|
|
|
1. Run the script:
|
|
```powershell
|
|
.\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
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Shell Script Version (Unix/Linux/macOS/WSL)</strong></summary>
|
|
|
|
## Prerequisites
|
|
|
|
- Unix-like operating system (Linux, macOS, WSL)
|
|
- OpenSSH client installed
|
|
- `sh` shell (POSIX-compliant)
|
|
- Forgejo instance running
|
|
|
|
## Usage
|
|
|
|
1. Make the script executable:
|
|
```bash
|
|
chmod +x forgejo-ssh-key-setup.sh
|
|
```
|
|
|
|
2. Run the script:
|
|
```bash
|
|
./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
|
|
```
|
|
|
|
</details>
|
|
|
|
## 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
|
|
|
|
<details>
|
|
<summary><strong>PowerShell Version</strong></summary>
|
|
|
|
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`
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Shell Script Version</strong></summary>
|
|
|
|
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
|
|
|
|
</details>
|
|
|
|
## License
|
|
|
|
This project is open source and available under the MIT License. |