git-ssh-custom-host

name	git-ssh-custom-host
description	Set up SSH authentication for custom Git hosts (non-standard ports, custom domains, VPN-dependent hosts) with verification workflow and troubleshooting for common connectivity issues.
version	1.0.0
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["Git","SSH","Authentication","Custom-Host","VPN","Network"],"related_skills":["github-auth","github-repo-management","github-pr-workflow"]}}

SSH Authentication for Custom Git Hosts

This skill sets up SSH-based authentication for Git hosts that aren't standard GitHub/GitLab.com (e.g., self-hosted GitLab, custom ports, internal domains, VPN-dependent hosts).

When to Use This Skill

• Connecting to self-hosted GitLab/Gitea/Gitea instances
• Using non-standard SSH ports (not port 22)
• Hosts accessible only via VPN/internal network
• Custom domain names that require DNS or /etc/hosts configuration
• When standard github-auth skill doesn't apply due to host specificity

Detection Flow

First, understand what kind of host we're dealing with:

# Get host details from user
echo \"Git host hostname (e.g., dev.fast-8.com):\"\nread GIT_HOST\necho \"Git host port (default 22):\"\nread GIT_PORT\necho \"Git username (usually 'git'):\"\nread GIT_USER

If no port specified, default to 22. If no username specified, default to 'git'.

Port Service Detection (Recommended)

Before configuring, verify what service is running on the target port:

# Test if port is reachable
nc -z $GIT_HOST $GIT_PORT && echo \"Port $GIT_PORT reachable\" || echo \"Port $GIT_PORT unreachable\"

# If reachable, check what service is responding
if nc -z $GIT_HOST $GIT_PORT; then
  echo \"Checking service type on port $GIT_PORT...\"
  # Make a brief connection to see if it's SSH or HTTP
  RESPONSE=$(echo -n \"\" | nc $GIT_HOST $GIT_PORT 2>&1 | head -5)
  if echo \"$RESPONSE\" | grep -q \"SSH\" || echo \"$RESPONSE\" | grep -q \"^SSH-\"; then
    echo \"✓ Detected SSH service on port $GIT_PORT\"
  elif echo \"$RESPONSE\" | grep -q \"HTTP\" || echo \"$RESPONSE\" | grep -q \"<html\" || echo \"$RESPONSE\" | grep -q \"<!DOCTYPE\"; then
    echo \"⚠ Detected HTTP service on port $GIT_PORT - this is likely the web UI, not SSH\"
    echo \"  Try checking if SSH is available on the standard port (22) instead\"
    # Suggest checking standard SSH port
    nc -z $GIT_HOST 22 && echo \"  Port 22 is reachable - SSH might be on standard port\" || echo \"  Port 22 also unreachable\"
  else
    echo \"? Unclear service type on port $GIT_PORT\"
  fi
fi

read GIT_USER

If no port specified, default to 22.
If no username specified, default to 'git'.

## Step-by-Step Setup

### 1. Check for Existing SSH Key

```bash
# Check for existing SSH keys
ls -la ~/.ssh/id_*.pub 2>/dev/null || echo "No SSH keys found"

# If user wants to use existing key, note the path
# If needs new key, generate one:
ssh-keygen -t ed25519 -C "user@domain" -f ~/.ssh/id_custom_git -N ""

2. Configure SSH Config for Custom Host

Create or update ~/.ssh/config with host-specific settings:

# Backup existing config if needed
cp ~/.ssh/config ~/.ssh/config.backup.$(date +%Y%m%d_%H%M%S) 2>/dev/null || true

# Add host configuration
cat >> ~/.ssh/config << EOF

# Custom Git host: $GIT_HOST
Host $GIT_HOST
    HostName $GIT_HOST
    Port ${GIT_PORT:-22}
    User ${GIT_USER:-git}
    IdentityFile ~/.ssh/id_custom_git
    IdentitiesOnly yes
    TCPKeepAlive yes
    ServerAliveInterval 30
    ServerAliveCountMax 3
EOF

# Set proper permissions
chmod 600 ~/.ssh/config

3. Add SSH Key to Agent

# Start ssh-agent if needed
eval "$(ssh-agent -s)" 2>/dev/null || true

# Add the key
ssh-add ~/.ssh/id_custom_git

# Verify it's loaded
ssh-add -l | grep id_custom_git

4. Test Connectivity

# Test SSH connection to the host
ssh -T $GIT_HOST

# Expected output varies by host:
# - GitLab: "Welcome to GitLab, @username!"
# - Generic: "PTY allocation request failed on channel 0" (still success if no permission error)
# - Success indicator: exit code 0 or 1 (but not 255 for network issues)

if [ $? -eq 255 ]; then
  echo "SSH connection failed - likely network/host issue"
elif [ $? -eq 1 ]; then
  echo "SSH connected but shell access restricted (normal for Git hosts)"
else
  echo "SSH connection successful"
fi

Troubleshooting Common Issues

A. Hostname Resolution Problems

If you get: ssh: Could not resolve hostname HOST: nodename nor servname provided, or not known

Solutions:

1. Check VPN connection - Ensure VPN is active if host is internal
2. Test DNS resolution:

   dig $GIT_HOST +short
   nslookup $GIT_HOST
   host $GIT_HOST
   

3. Temporary /etc/hosts fix (if you have IP):

   # Get IP from user or network admin
   echo "IP_ADDRESS $GIT_HOST" | sudo tee -a /etc/hosts > /dev/null
   

4. Check alternative hostname - Maybe there's an internal DNS name

B. Connection Timeout/Network Issues

If you get: ssh: connect to host HOST port PORT: Connection timed out or Operation timed out

Solutions:

1. Verify VPN is active and allows traffic to target host/port
2. Test port connectivity:

   nc -z $GIT_HOST $GIT_PORT && echo "Port open" || echo "Port blocked/unreachable"
   

3. Check firewall settings on both client and server sides
4. Try with verbose mode to see where it fails:

   ssh -v -T $GIT_HOST
   

C. Authentication Failures

If you get: Permission denied (publickey) or similar auth errors

Solutions:

1. Verify key is loaded: ssh-add -l should show your key
2. Check key permissions: chmod 600 ~/.ssh/id_custom_git
3. Confirm public key is added to host (GitLab/Gitea settings → SSH Keys)
4. Check for multiple identities: Try specifying key explicitly:

   ssh -i ~/.ssh/id_custom_git -T $GIT_HOST
   

5. Verify SSH config is correct: ssh -G $GIT_HOST | grep -E "(hostname|user|port|identityfile)"

D. Host Key Verification

If you get: The authenticity of host '[HOST]:PORT ([IP]:PORT)' can't be established.

Normal on first connection - verify host key fingerprint with admin, then:

ssh-keyscan -p $GIT_PORT $GIT_HOST >> ~/.ssh/known_hosts

Verification Steps

After setup, verify everything works:

# 1. SSH config test
ssh -G $GIT_HOST | grep -E "(hostname|user|port|identityfile)"

# 2. Key loading test
ssh-add -l | grep id_custom_git

# 3. Connection test
ssh -T $GIT_HOST

# 4. Git test (if you have a repo URL)
# Replace with actual repo path
git ls-remote ssh://$GIT_HOST:${GIT_PORT:-22}/~$GIT_USER/test-repo.git

Usage Examples

Example 1: Standard GitLab on Custom Port

GIT_HOST="dev.fas-8.com"
GIT_PORT="9874"
GIT_USER="git"

Example 2: Self-hosted Gitea

GIT_HOST="git.internal.company.com"
GIT_PORT="2222"  # common alternative
GIT_USER="git"

Example 3: VPN-only Host with /etc/hosts workaround

# After getting IP from network admin:
GIT_HOST="gitlab.vpn.internal"
GIT_IP="10.15.20.5"
# Add to /etc/hosts: sudo sh -c "echo \"$GIT_IP $GIT_HOST\" >> /etc/hosts"

Integration with Git Workflows

Once SSH is working, use standard git commands:

# Clone
git clone ssh://$GIT_HOST:${GIT_PORT:-22}/$GIT_USER/repo-name.git

# Or if using SSH config host alias:
git clone $GIT_HOST:$GIT_USER/repo-name.git

# Standard git push/pull/fetch will use the SSH config automatically

Cleanup / Key Management

To remove this host configuration later:

1. Remove host block from ~/.ssh/config
2. Remove key from ssh-agent: ssh-add -d ~/.ssh/id_custom_git
3. Optionally delete key files: rm ~/.ssh/id_custom_git*
4. Remove from known_hosts if needed: ssh-keygen -R $GIT_HOST -p $GIT_PORT

---