# SSH Key Setup for GitLab
This guide explains how to configure SSH keys for secure, password-free authentication with GitLab.
## Quick Check
Check if you already have SSH configured:
```bash
# Test SSH connection to GitLab
ssh -T git@gitlab.com
```
If you see `Welcome to GitLab, @username!`, you're already set up! š
## Step 1: Generate SSH Key
### Option A: ED25519 (Recommended - Most Secure)
```bash
ssh-keygen -t ed25519 -C "your-email@example.com"
```
### Option B: RSA (Compatible with older systems)
```bash
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
```
When prompted:
- **Location**: Press Enter to use default (`~/.ssh/id_ed25519` or `~/.ssh/id_rsa`)
- **Passphrase**: Optional but recommended for extra security
## Step 2: Start SSH Agent
```bash
# Start the ssh-agent
eval "$(ssh-agent -s)"
# Add your key to the agent
ssh-add ~/.ssh/id_ed25519 # or ~/.ssh/id_rsa for RSA
```
## Step 3: Copy Public Key
### Linux/macOS:
```bash
# For ED25519
cat ~/.ssh/id_ed25519.pub | pbcopy # macOS
cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard # Linux with xclip
cat ~/.ssh/id_ed25519.pub # Display to copy manually
```
### Windows (PowerShell):
```powershell
Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard
```
## Step 4: Add Key to GitLab
1. Go to GitLab SSH Keys settings:
- Direct link: https://gitlab.com/-/profile/keys
- Or navigate: Profile ā Settings ā SSH Keys
2. Paste your public key in the "Key" field
3. Add a descriptive title (e.g., "MacBook Pro - Work")
4. Choose expiration date (optional)
5. Click "Add key"
## Step 5: Test Connection
```bash
ssh -T git@gitlab.com
```
You should see:
```
Welcome to GitLab, @your-username!
```
## Using SSH with pg-api Scripts
Once SSH is configured, the scripts will automatically detect and use it:
```bash
# The script will auto-detect SSH and use it
python3 scripts/create_gitlab_repo.py --token YOUR_TOKEN --push
# Output will show:
# š SSH key detected, using SSH for push...
```
## Multiple SSH Keys
If you have multiple GitLab accounts or keys:
### 1. Create SSH Config
Create/edit `~/.ssh/config`:
```ssh-config
# Personal GitLab account
Host gitlab.com-personal
HostName gitlab.com
User git
IdentityFile ~/.ssh/id_ed25519_personal
# Work GitLab account
Host gitlab.com-work
HostName gitlab.com
User git
IdentityFile ~/.ssh/id_ed25519_work
# Default
Host gitlab.com
HostName gitlab.com
User git
IdentityFile ~/.ssh/id_ed25519
```
### 2. Use with Git
```bash
# For personal account
git remote add origin git@gitlab.com-personal:username/pg-api.git
# For work account
git remote add origin git@gitlab.com-work:username/pg-api.git
```
## Troubleshooting
### Permission Denied
```bash
# Check if key is added to agent
ssh-add -l
# If not listed, add it
ssh-add ~/.ssh/id_ed25519
```
### Wrong Key Being Used
```bash
# Verbose mode to see which key is being used
ssh -vT git@gitlab.com
# Force specific key
ssh -i ~/.ssh/specific_key -T git@gitlab.com
```
### Key Not Working on GitLab
1. Ensure you copied the PUBLIC key (`.pub` file), not the private key
2. Check for extra spaces or line breaks when pasting
3. Verify the email matches your GitLab account (optional but helpful)
### Windows Issues
```powershell
# Ensure OpenSSH is enabled
Start-Service ssh-agent
```
## Security Best Practices
1. **Use Passphrases**: Add a passphrase to your SSH key for extra security
2. **Separate Keys**: Use different keys for different services
3. **Rotate Keys**: Periodically generate new keys (every year)
4. **Limit Key Scope**: Use deploy keys for CI/CD with limited permissions
5. **Protect Private Keys**: Never share or commit private keys
## Benefits of SSH over HTTPS
- ā
No need to enter username/password
- ā
No need to store tokens in URLs
- ā
More secure than password authentication
- ā
Works with 2FA enabled
- ā
Easier for automated scripts
- ā
Better for frequent pushes
## Quick Setup Script
Save as `setup-gitlab-ssh.sh`:
```bash
#!/bin/bash
# Generate SSH key
echo "Generating SSH key..."
ssh-keygen -t ed25519 -C "$1" -f ~/.ssh/id_ed25519_gitlab -N ""
# Start SSH agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_gitlab
# Display public key
echo -e "\nš Copy this public key to GitLab:\n"
cat ~/.ssh/id_ed25519_gitlab.pub
echo -e "\nš Add it here: https://gitlab.com/-/profile/keys"
echo -e "\nā
Then test with: ssh -T git@gitlab.com"
```
Usage:
```bash
chmod +x setup-gitlab-ssh.sh
./setup-gitlab-ssh.sh "your-email@example.com"
```
## Integration with pg-api
The pg-api scripts automatically detect SSH keys:
```python
# The script checks for SSH keys in this order:
1. ~/.ssh/id_ed25519
2. ~/.ssh/id_rsa
3. ~/.ssh/id_ecdsa
# Then tests connection to GitLab
# If successful, uses SSH for all Git operations
```
## Deploy Keys (For CI/CD)
For automated deployments, use deploy keys instead:
1. Generate a specific key:
```bash
ssh-keygen -t ed25519 -C "pg-api-deploy" -f ~/.ssh/pg-api-deploy
```
2. Add as Deploy Key in GitLab:
- Go to: Project ā Settings ā Repository ā Deploy Keys
- Add the public key
- Enable "Write access" if needed
3. Use in CI/CD:
```yaml
before_script:
- eval $(ssh-agent -s)
- echo "$SSH_PRIVATE_KEY" | ssh-add -
```
## Related Documentation
- [GitLab SSH Documentation](https://docs.gitlab.com/ee/user/ssh.html)
- [GitHub's SSH Guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
- [SSH Academy](https://www.ssh.com/academy/ssh/keygen)