Skip to content

Git & SSH Setup

This guide walks you through configuring Git and SSH to work with GitLab at gitlab.shared.cwiq.io.

Prerequisites

Step 1: Generate an SSH Key

ssh-keygen -t ed25519 -C "your.name@cwiq.io"

Accept the default location (~/.ssh/id_ed25519) and set a passphrase.

ssh-keygen -t ed25519 -C "your.name@cwiq.io"

Accept the default location (C:\Users\<username>\.ssh\id_ed25519) and set a passphrase.

Step 2: Add Your Key to GitLab

  1. Copy your public key:

    pbcopy < ~/.ssh/id_ed25519.pub

    cat ~/.ssh/id_ed25519.pub
# Copy the output manually

    Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

  2. Open GitLab SSH Keys settings

  3. Paste your public key
  4. Add a title (e.g., "Work Laptop")
  5. Click Add key

Step 3: Configure SSH for GitLab

GitLab uses port 2222 for SSH (not the standard port 22). You need to add an entry to your SSH config file.

Edit ~/.ssh/config:

Host gitlab.shared.cwiq.io
    HostName gitlab-shared-cwiq-io
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    AddKeysToAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

Edit C:\Users\<username>\.ssh\config:

Host gitlab.shared.cwiq.io
    HostName gitlab-shared-cwiq-io
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    AddKeysToAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

Why the Tailscale hostname?

The HostName uses the Tailscale MagicDNS hostname because SSH port 2222 is not exposed through the public load balancer. All Git-over-SSH traffic routes through the Tailscale network. If MagicDNS is not resolving, you can find the current IP with tailscale status | grep gitlab.

Step 4: Test Your Connection

ssh -T git@gitlab.shared.cwiq.io

Expected output:

Welcome to GitLab, @your.username!

Step 5: Configure Git Identity

git config --global user.name "Your Name"
git config --global user.email "your.name@cwiq.io"

Step 6: Clone a Repository

git clone git@gitlab.shared.cwiq.io:orchestrator/platform.git

Multiple GitLab Instances

If you also need access to the dev GitLab, add a second entry to your SSH config:

Host gitlab.dev.cwiq.io
    HostName gitlab-dev-cwiq-io
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

HTTPS Alternative

If SSH is problematic, you can use HTTPS with a personal access token:

  1. Create a token at GitLab Access Tokens
  2. Select scopes: read_repository, write_repository
  3. Clone using HTTPS:
git clone https://gitlab.shared.cwiq.io/orchestrator/platform.git
# Username: your_gitlab_username
# Password: your_personal_access_token

Troubleshooting

Connection refused / timeout

# Verify Tailscale is connected
tailscale status | grep gitlab

# Test SSH connectivity with verbose output
ssh -vT -p 2222 git@gitlab.shared.cwiq.io

Common causes:

  • Tailscale not connected (most common)
  • SSH config file missing or incorrect HostName

Permission denied (publickey)

# Check SSH agent has your key loaded
ssh-add -l

# Add key to agent if missing
ssh-add ~/.ssh/id_ed25519

Also verify the public key is added in GitLab (Settings > SSH Keys).

Host key verification failed

This usually happens when the GitLab server has been rebuilt or its SSH host key has changed. Before removing the old key, verify with your admin that the server was recently changed.

If confirmed by your admin:

ssh-keygen -R "[gitlab.shared.cwiq.io]:2222"
ssh -T git@gitlab.shared.cwiq.io
# Verify the new fingerprint matches what your admin provides

Warning

If the server was NOT recently changed, a host key mismatch could indicate a network issue. Contact the infrastructure team before proceeding.