maxiaof/github-hosts: a daily-updated hosts file for GitHub access from mainland China

What maxiaof/github-hosts actually solves

GitHub is reachable from mainland China on most days and unreachable on others. The failure is usually DNS-level: the resolver returns an address that is slow or filtered, so the browser or git client hangs before any TLS handshake. This repository sidesteps the resolver entirely. It publishes a block of hostname-to-IP pairs, wrapped between #Github Hosts Start and #Github Hosts End markers, and the README instructs the reader to append that block to the system hosts file. Once the entry is in place, the operating system answers github.com from the local file instead of asking a DNS server. There is no daemon, no background process, no proxy port to configure. The audience is individual developers and workstations that need github.com, api.github.com, gist.github.com and raw.githubusercontent.com to resolve reliably, and who would rather edit one text file than run a tunnel.

How the hosts block is structured and refreshed

The block is a flat list of IP addresses followed by hostnames. The README's copy shows entries such as 140.82.113.4 github.com, 140.82.114.6 api.github.com, 185.199.108.133 raw.githubusercontent.com, and 140.82.112.10 codeload.github.com, plus asset hosts under github-production-release-asset-2e65be.s3.amazonaws.com and github-production-user-asset-6210df.s3.amazonaws.com. It also carries a header comment with the update date and the raw URL of the file, and a trailing comment line marking the end of the block. That header matters: it is the only version marker a reader gets. The repository itself contains a hosts file at the root, a pom.xml and a src/ directory, so the update is produced by a Java program rather than by hand, but the README does not describe how that program resolves the addresses or how often it runs. The description claims daily updates, and the last push to the repository was on 2026-09-23, which is consistent with a scheduled job. What the README does not document is what happens when a mapping goes stale between runs.

Installing the block on Windows, macOS and Linux

There is nothing to install in the package-manager sense. You copy the block from the README or from the raw hosts file and append it to your system hosts file. The README gives the paths: C:\Windows\System32\drivers\etc\hosts on Windows, /etc/hosts on macOS and Linux. On Windows it suggests Notepad; on Linux and macOS it suggests root access via sudo vi /etc/hosts. Once the block is appended, open the hosts file and confirm it sits at the end and the Update Time comment matches the current date. If the entries do not take effect, the README lists the flush commands:

ipconfig /flushdns
sudo killall -HUP mDNSResponder
sudo nscd restart

The README labels these as the Windows, Mac and Linux refreshes in that order. If flushing does not help, the README's own tip is to reboot. One caution the README does not state: appending the block repeatedly stacks duplicate entries. Remove the old block between #Github Hosts Start and #Github Hosts End before pasting a new one, or the file grows without bound.

Where this approach breaks down

A hosts file is a static override, so it is wrong the moment GitHub's edge addresses change. GitHub serves through a CDN and rotates addresses; the README's list mixes 140.82.11x.x, 185.199.1xx.x, 192.0.66.2 and several AWS S3 ranges. If any of those rotate and the daily job has not caught up, connections to the affected hostname fail or land on an address that no longer serves the certificate you expect. The block also covers a fixed set of names. Any GitHub subdomain not in the list still goes through normal DNS and can still be blocked, so a workflow that depends on an unlisted host will behave inconsistently. There is no rollback mechanism described: recovery means deleting the block by hand. And because the entries are IP pins, they interact badly with VPNs and corporate DNS that expect to resolve those names themselves. If your machine is behind a managed resolver, appending these lines can route GitHub traffic outside the policy your network enforces.

How it differs from SwitchHosts and from a proxy

SwitchHosts is the closest tool in the related searches, and the difference is one of scope. SwitchHosts is a hosts file manager: it stores multiple host groups, switches between them, and can pull a remote hosts file on a schedule. maxiaof/github-hosts is the content, not the manager. You can point SwitchHosts at the raw URL and let it refresh the block, which removes the manual copy step and the duplicate-entry problem. A proxy or tunnel takes the opposite approach: instead of pinning addresses, it forwards traffic through a reachable endpoint and lets DNS resolve normally. That covers arbitrary subdomains and survives IP rotation, at the cost of running a client and routing traffic you may not want routed. The hosts approach is lighter and needs no client, but it only fixes the names someone remembered to list.

Maintenance, licence and what to check before trusting it

The repository is not archived, and its last push was on 2026-09-23, so the update pipeline appears to be running. That is the whole maintenance story the repository supports: a scheduled Java job writes a hosts file, and the README is regenerated from README_TEMPLATE.md. There are no releases, so there is no version to pin and no changelog to read; the Update Time comment inside the block is your only signal of freshness. The LICENSE file exists at the repository root, but the licence identifier is reported as NOASSERTION, meaning GitHub could not classify it automatically. Read the LICENSE file yourself before redistributing the block inside a product or a corporate image; copying a hosts list into a distributed artifact is a redistribution, and the terms are not summarized here. Upgrading means re-fetching and re-pasting, which is a manual operation unless you wire the raw URL into a hosts manager.

Editorial conclusion

Adopt it if you want a zero-install, no-proxy fix for GitHub connectivity on a machine you control, and you are willing to re-paste the block when GitHub rotates its edge IPs. Do not adopt it if you need coverage for every GitHub subdomain, if you cannot edit a root-owned hosts file, or if you expect an updater: the repository ships a text block and a README, and the automation that produces it is not documented there. Before relying on it, open the hosts file in the repository root, check the Update Time comment against the last push, and confirm the domains you actually use (raw.githubusercontent.com, codeload.github.com, objects.githubusercontent.com) are present in the block.

Frequently asked questions

Official sources

1. Issues
2. maxiaof/github-hosts on GitHub
3. README