Github pages is a convenient way to host a static website like a blog, but if you want to migrate it to another host with minimun impact on the site's performance in Google Search, it pains due to Github pages doesn't provide a server config to allow the HTTP redirects.

Why does redirect matter?

Essentially Redirecting URLs is the canonical way to tell your visitors and search engine that your existing URL has a new location, so your existing SEO credit can remain. Read Google Search Document for more details.

There IS a solution

Thanks to finisky's blog post, there is a clever way to exploit the Github Pages Custom domain feature for the redirects.

Let's say you have your old website on Github pages https://example.github.io, and now you want to redirect it to a new host exmaple.com; we also assume that you have already got everything ready and the new site on example.com is working properly.

Buckle up! Let me walk you through about how to migrate the old github pages site.

301 Redirect from Github Pages

Although there is no explicit configuration option to redirect Github pages to other domain/host, there is one approach, actually it is a side effect of custom domain feature of Githug pages, follow the below two steps to set the custom domain features:

1. DNS setting on your domain register, add a CNAME record to point the blog.example.com to example.github.io; this is mandatory to proceed the step 2 as Github will verify the DNS for your domain change.

2. Set custom domain from Github repo settings, i.e. put blog.exmaple.com into the custom domain input box.

Once it passed the verification, you can try to access http://exmaple.github.io, it should redirect to blog.example.com now.

Redirect back with CNAME

Again, on your domain regiter, change the CNAME blog.exmaple.com back exmaple.com.

Now both example.github.io and blog.exmaple.com points to the same site example.com. Host redirecting is done!

URL level redirects

If you have the exact same URL patterns for both sites, you can skip this section. Otherwise the access of legacy url (e.g. http://exmaple.github.io/foo ) will cause a 404 not_found error because on the new site there is no such path /foo available. There are many wasy to implement URL level directs, nginx map directive is one of them. Say you have a long list of url mapping like this:

https://example.github.io/foo_1 => https://example.com/foo_2 https://example.github.io/bar_1 => https://example.com/bar_2 https://example.github.io/qux_1 => https://example.com/qux_2 ...

1. define a map file /etc/nginx/redirect.map as follows,

/foo_1 /foo_2; /bar_1 /bar_2; /qux_1 /qux_2; ...

2. update the nginx.conf

# see http://nginx.org/en/docs/hash.html map_hash_bucket_size 256; map $request_uri $new_uri { include /etc/nginx/redirect.map; } server { listen 80; server_name your_server_name; if ($new_uri) { return 301 $new_uri; } ... }

Migrate Google Search results

Last but not the least, once you have done all the above settings, you can use Change of Address Tool to migrate the serach result, please refer to https://support.google.com/webmasters/answer/9370220?hl=en for details.

That's it! 🎉