Deploying code to a corporate Gerrit instance often involves navigating layered constraints—internal DNS, SSH/GPG trust chains, cross-platform tooling (e.g., WSL), and nested repository structures. This guide walks through a production-ready workflow to initialize and push your first change, grounded in real-world enterprise infrastructure.

Environment Context

The target setup includes:

• Gerrit 3.8+ as the code review gateway, enforcing mandatory Change-Id and signed commits
• WSL2 (Ubuntu 22.04) as the primary development shell on Windows
• Corporate intranet with split-DNS, internal CA-signed certificates, and no public internet access for build tools

Phase 1: Identity & Authentication Setup

1.1 Git Identity

git config --global user.name "Alex Chen"
git config --global user.email "alex.chen@corp.internal"

1.2 SSH Key Pair (Ed25519)

ssh-keygen -t ed25519 -f ~/.ssh/gerrit_id -C "alex.chen@corp.internal"
cat ~/.ssh/gerrit_id.pub

Paste the full output into Gerrit’s Settings → SSH Public Keys. Then configure SSH to use this key:

echo 'Host gerrit.internal
  HostName 10.117.115.89
  User alex.chen
  IdentityFile ~/.ssh/gerrit_id
  Port 29418' >> ~/.ssh/config
chmod 600 ~/.ssh/config

1.3 GPG Signing (Enforced by Policy)

gpg --batch --passphrase '' --quick-generate-key "alex.chen@corp.internal" rsa4096 sign never
KEY_ID=$(gpg --list-secret-keys --key-format=short | awk '/^sec/ {print $2}' | cut -d/ -f2 | head -1)
git config --global user.signingkey "$KEY_ID"
git config --global commit.gpgsign true

Export and upload the ASCII-armored public key to Gerrit → Settings → GPG Keys:

gpg --armor --export "alex.chen@corp.internal" > gpg-public.asc

Phase 2: Network & Toolchain Bridging

2.1 Bypassing DNS Limitations

WSL2 inherits Windows’ DNS resolver but cannot resolve internal domains due to missing domain suffix search lists. Instead of editing /etc/resolv.conf (which resets on restart), define static host resolution:

echo "10.117.115.89 gerrit.internal" | sudo tee -a /etc/hosts

2.2 Reusing Windows SSH Keys Securely

If keys already exist in Windows Git Bash:

mkdir -p ~/.ssh
cp /mnt/c/Users/Alex/.ssh/gerrit_id* ~/.ssh/
chmod 600 ~/.ssh/gerrit_id
chmod 644 ~/.ssh/gerrit_id.pub

Phase 3: Repository Initialization

3.1 Clone with IP-Based Access

git clone ssh://gerrit.internal/team/platform-core.git
cd platform-core

3.2 Install commit-msg Hook Without HTTPS Cert Errors

Gerrit’s hook endpoint uses an internal domain certificate invalid for raw IP access. Use HTTP with strict host verification disabled only for this step:

curl -k http://gerrit.internal/tools/hooks/commit-msg > .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg

This hook injects a Change-Id line into every commit message—required for Gerrit to track patch sets.

Phase 4: Handling Subproject Inclusion

4.1 Detecting Nested Repositories

Running git add ci-tools/ yields:

Warning: adding embedded git repository: ci-tools/

This occurs because ci-tools/ contains its own .git directory.

4.2 Flatten Subprojects Temporarily

For initial submission—prioritizing correctness over history preservation—remove version control metadata from subdirectories:

find ci-tools/ -name ".git" -type d -exec rm -rf {} + 2>/dev/null || true
git add ci-tools/

Note: For long-term maintenance, replace this with git submodule add after verifying upstream permissions.

Phase 5: Committing and Submitting to Review

5.1 Atomic Signed Commit

git add .
git commit -S -m "feat(auth): integrate SSO token refresh logic"

The -S flag ensures GPG signing; Gerrit rejects unsigned submissions when policy is enabled.

5.2 Push to Review Queue

git push origin HEAD:refs/for/main

Key points:

• refs/for/main routes the push to Gerrit’s review pipeline—not direct merge
• Direct pushes to refs/heads/main are blocked unless you hold Force Push permission

5.3 Verification Output

A successful response includes:

remote: New Changes:
remote:   https://gerrit.internal/c/team/platform-core/+/19890140

That URL opens the web-based code review interface where reviewers can comment, approve, or request changes.

Troubleshooting Flow Summary

• Vlaidate layer-by-layer: Confirm SSH connectivity before testing Git commands; verify GPG signing before pushing.
• Perfer IP + /etc/hosts over DNS hacks in ephemeral environments like WSL2.
• Never skip the commit-msg hook—without Change-Id, Gerrit treats each push as a new change, breaking patch-set continuity.
• Assume internal tooling diverges from public docs: Certificate validation, port numbers, and branch naming (main vs master) vary across installations.