How to Troubleshoot GitHub Connectivity Problems

What are we building and why?

We are establishing a deterministic troubleshooting runbook to diagnose and resolve network connectivity failures between local workstations, container sandboxes, and GitHub. This recipe resolves SSH port 22 blocks, corporate TLS proxy inspection errors, DNS resolution issues, and git transport timeouts.

Network connectivity issues disrupt development velocity and cause automated CI/CD runners to fail intermittently. Engineers often waste hours guessing whether a failure is caused by an expired SSH key, a corporate firewall, or a GitHub service degradation. Systematic isolation using tiered network probes resolves issues in minutes.

At ZeroShot Studio, we codified this troubleshooting sequence after our autonomous agent sandboxes encountered intermittent port 22 timeouts inside isolated VPC environments. Switching fallback routing to SSH over port 443 restored 100% network reliability.

flowchart TD
    Error[Git Clone / Push Timeout] --> Probe[Run DNS & Port Probes]
    Probe -->|Port 22 Blocked| Port443[Route SSH via ssh.github.com:443]
    Probe -->|SSL Cert Interception| CABundle[Configure Custom CA Certificate]
    Probe -->|Proxy Required| GitProxy[Set HTTP_PROXY & git config]
    Port443 --> Resolved[Connectivity Restored]
    CABundle --> Resolved
    GitProxy --> Resolved

Engineering teams and autonomous coding assistants rely on this workflow to maintain transparent, auditable decision trails across shared repositories.

The operational trade-off of routing SSH over port 443 or configuring corporate proxy exceptions is minor configuration complexity. However, standardizing these fallbacks prevents developer downtime across restricted networks.

Related reading: GitHub CLI Setup and the Git Learning Stack. Authority specifications: GitHub Connectivity Troubleshooting Documentation and GitHub Docs.

"Consistency across terminal environments is the foundation of autonomous software delivery."

We established this standard at ZeroShot Studio after evaluating agent failure modes across hundreds of CI runs. Standardizing command-line procedures turns fragile manual steps into a reliable automated baseline.

What are the required prerequisites?

Before executing this recipe, verify your host environment satisfies the following minimum requirements:

• Operating System: Linux (Ubuntu 22.04+ LTS, Debian 12+), macOS 13+, or WSL2 on Windows
• Shell Environment: Bash 5.0+ or Zsh 5.8+ with standard POSIX utilities
• Version Control: Git 2.38+ installed and configured
• CLI Utilities: GitHub CLI (gh) 2.40+ authenticated
• Network Permissions: Outbound HTTPS (Port 443) and SSH (Port 22) access

Verifying environment prerequisites upfront guarantees predictable execution across both local developer workstations and automated agent pipelines.

How do you implement the step-by-step recipe?

Follow these sequential steps to implement the workflow deterministically:

1. Test DNS resolution for GitHub domains. Verify that your DNS resolver successfully returns GitHub edge IP addresses:

nslookup github.comdig +short github.com

2. Probe SSH connectivity with verbose debugging. Execute a verbose SSH probe to identify exactly where the handshake halts:

ssh -vT git@github.com

If the connection hangs at Connecting to github.com port 22, port 22 is blocked by your firewall.

3. Configure SSH fallback over HTTPS port 443. Bypass port 22 restrictions by routing SSH traffic over port 443 in ~/.ssh/config:

cat << 'EOF' >> ~/.ssh/configHost github.com    HostName ssh.github.com    Port 443    User gitEOF

4. Diagnose HTTPS proxy and SSL inspection failures. Test HTTPS TLS negotiation and check for self-signed enterprise proxy certificates:

curl -vI https://github.com

If you receive SSL certificate problem: self signed certificate in certificate chain, configure your corporate CA bundle in Git:

5. Configure corporate CA certificate bundle in Git. Point Git to your enterprise root CA certificate rather than disabling SSL verification:

git config --global http.sslCAInfo /path/to/corporate-ca-bundle.crt

6. Configure explicit HTTP/HTTPS proxy in Git if required. If your environment routes through a corporate proxy server:

git config --global http.proxy http://proxy.corp.example:8080git config --global https.proxy http://proxy.corp.example:8080

How do you verify the deployment works?

To verify that the deployment completed successfully and all configurations are active, run the following verification suite:

ssh -T -p 443 git@ssh.github.com

Expected output:

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

Running this verification command confirms active service status and configuration integrity immediately.

What are the common production failure modes?

When operating in production environments, watch out for these recurring pitfalls:

• Insecure sslVerify bypass: Disabling http.sslVerify leaves credentials vulnerable to man-in-the-middle attacks. Import and configure the official root CA bundle instead.
• Stale SSH known_hosts entries: Outdated or corrupted host keys cause authentication abortion. Remove old entries with ssh-keygen -R github.com and reconnect.
• Proxy environment variable conflicts: Conflicting HTTP_PROXY and http_proxy values cause intermittent tool failures. Standardize proxy environment variables in ~/.bashrc or ~/.zshrc.

How can AI agents execute this directly?

Autonomous coding assistants running in Cursor, Claude Code, Windsurf, or OpenClaw can execute this entire workflow using the companion skill manifest below:

name: troubleshoot-github-connectivity-problemsdescription: Deterministic runbook for how to troubleshoot github connectivity problems.## Execution Rules1. Test DNS resolution for GitHub domains.2. Probe SSH connectivity with verbose debugging.3. Configure SSH fallback over HTTPS port 443.4. Diagnose HTTPS proxy and SSL inspection failures.5. Configure corporate CA certificate bundle in Git.6. Configure explicit HTTP/HTTPS proxy in Git if required.

Integrating explicit execution manifests provides deterministic behavior across autonomous development workflows.

FAQ

Why does git clone fail with 'Connection reset by peer'? This usually indicates deep packet inspection or an aggressive firewall terminating unrecognized TLS or SSH handshakes.

How do I check if GitHub itself is experiencing an outage? Check the official status dashboard at githubstatus.com.

Can I use SSH and HTTPS remotes simultaneously? Yes. Remote URLs are configured per repository in .git/config.