Josh Hammer's Blog

From life to work and everything in between, these are my words and my thoughts.

Route53 And GitHub Pages Cutover

Route53 And GitHub Pages Cutover

This runbook moves the public website from the WordPress server to the GitHub Pages project site at https://halimer.github.io/halimer/ while keeping https://halimer.com as the public, canonical URL.

Do not change Route53 mail records. In particular, preserve all MX, TXT, DKIM, SPF, DMARC, and any email-provider verification records.

Current State

Record Current value Action
halimer.com A 143.47.104.27 Replace with the four GitHub Pages A records.
www.halimer.com CNAME halimer.com Change to Halimer.github.io.
halimer.com MX/TXT and other mail records Existing values Do not change.

The GitHub repository is a project site, so its GitHub Pages fallback address is https://halimer.github.io/halimer/. A repository named Halimer.github.io would be required to serve the root https://halimer.github.io/ address. This is not required for halimer.com to work.

1. Save DNS And Server Rollback Details

  1. In Route53, open the halimer.com hosted zone.
  2. Export or screenshot every existing record before editing it.

  3. Record the current web records for rollback:

    halimer.com.      A      143.47.104.27
www.halimer.com.  CNAME  halimer.com.
  4. Do not decommission the WordPress server yet. Leave it running until the GitHub Pages site and HTTPS are verified.

2. Enable GitHub Actions Deployment

The repository includes .github/workflows/pages.yml, which builds Jekyll and deploys the generated _site artifact. The GitHub Pages setting must use that workflow rather than legacy branch publishing.

  1. Open https://github.com/Halimer/halimer/settings/pages.
  2. Under Build and deployment, select Source: GitHub Actions.
  3. Confirm the existing Custom domain field contains halimer.com.
  4. Push or rerun the Build and deploy GitHub Pages workflow from the default branch.
  5. Wait for both build and deploy jobs to succeed.

Do not select main and / as a legacy Pages source. That publishes repository source files instead of the Jekyll artifact built by the workflow.

3. Configure Domain Verification

Before changing traffic, add GitHub’s domain-verification record if GitHub offers it in the Pages settings.

  1. Open the Pages custom-domain settings.
  2. If GitHub displays a verification name and value, create exactly that TXT record in Route53.
  3. Wait until GitHub reports the domain as verified.

The verification record name is account-specific. Do not guess or replace it with a generic record.

4. Update Only Web Records In Route53

In the halimer.com hosted zone, edit only the records below. A Route53 Alias record cannot target GitHub Pages, so use standard DNS records.

Apex Domain: halimer.com

Replace the existing single A record with these four A values. Use Simple routing and a TTL of 300 seconds or lower.

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Add these four AAAA values if the hosted zone does not already contain AAAA records for halimer.com:

2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

Do not create a CNAME at the apex. DNS does not permit an apex CNAME because the apex must also contain NS and SOA records.

www Subdomain

Replace the current record with one standard CNAME record:

www.halimer.com.  CNAME  Halimer.github.io.

Use a TTL of 300 seconds or lower. The target must be Halimer.github.io without /halimer or any other path; DNS records cannot contain URL paths.

5. Verify DNS, Content, And HTTPS

DNS caches can take longer than the record TTL to update globally. Do not retire WordPress until all checks pass.

dig +short halimer.com A
dig +short halimer.com AAAA
dig +short www.halimer.com CNAME
curl -I http://halimer.com
curl -I https://halimer.com
curl -I https://www.halimer.com

Expected results:

  1. halimer.com returns all four GitHub Pages IPv4 addresses and, if configured, all four IPv6 addresses.
  2. www.halimer.com returns Halimer.github.io. as its CNAME.
  3. https://halimer.com serves the migrated Jekyll site.
  4. https://www.halimer.com redirects to the selected canonical host.
  5. GitHub Pages settings show the domain as verified and the latest workflow’s deploy job succeeded.

6. Enable GitHub-Managed HTTPS

GitHub Pages provisions and renews the certificate. Do not copy the WordPress server’s Let’s Encrypt certificate or private key to GitHub.

  1. Wait for GitHub Pages to detect the new DNS records and issue its certificate. This can take several minutes and occasionally up to 24 hours.
  2. In Pages settings, enable Enforce HTTPS once the checkbox becomes available.

  3. Test the certificate and redirect behavior:

    curl -I https://halimer.com
curl -I https://www.halimer.com
  4. Confirm browsers show a valid certificate for halimer.com before stopping the old server’s certificate renewal.

7. Retire WordPress Only After Cutover

After at least 24 hours of successful GitHub Pages traffic and HTTPS verification:

  1. Take a final WordPress database and uploads backup.
  2. Keep the WordPress XML export and any unpublished content in secure storage.
  3. Disable the WordPress web service and scheduled Let’s Encrypt renewal.
  4. Keep the server snapshot or backup for the agreed retention period before deleting the server.

Rollback

If GitHub Pages does not serve the site correctly, restore only the two web records:

halimer.com.      A      143.47.104.27
www.halimer.com.  CNAME  halimer.com.

Remove the GitHub Pages A and AAAA values, then confirm the WordPress server and its Let’s Encrypt certificate are still active. Do not alter MX, TXT, DKIM, SPF, DMARC, or other non-web Route53 records during rollback.