How to Connect a Custom Domain to GitHub Pages

Point a domain at a static GitHub Pages site, verify ownership, enable HTTPS and test the expected URLs.

How to Connect a Custom Domain to GitHub Pages

Quick answer

Publish the site at its default Pages address, then use GitHub’s domain settings and exact DNS records for your chosen hostname. Verify control, wait for certificate provisioning and test a deep link on the final public address.

Move a documentation site from an account URL

A repository already publishes documentation successfully at its default Pages URL. The team chooses docs.example.com for the permanent address. It checks that the generated documentation links use the expected deployment base and that a nested guide and its stylesheet work. In GitHub it follows the domain verification process for the organization that owns the project. The DNS administrator adds only the settings GitHub’s current instructions give for the specific subdomain and leaves the company’s separate MX and sender policy entries intact. After validation and TLS provisioning, the team activates HTTPS where the control is available and checks that the custom address loads from a normal browser.

Test both URLs that a user bookmarks and links a crawler follows. An SVG reference, an image relative to a nested path and a generated navigation link can all make different assumptions about the root. Inspect the actual published release because GitHub Pages serves the built static output. If the project serves dynamic support forms, record which external app receives them and review the allowed origin during the move. A plain custom-domain setup cannot launch a Node runtime for a server API. For an account using an apex address, review the current GitHub instructions for both the root and www. Follow GitHub’s verified-domain protections, avoid unnecessary wildcard DNS and record how to remove the old records safely when the project is retired.

Confirm GitHub Pages fits your site

A collection of help pages includes static text, images and a link to a hosted form.

Begin with a simple case where you can tell if things went wrong even before looking at any reports. Keep a copy of the starting inputs and confirm the result that ought to follow from them. Ask what the user will see and what the underlying system ought to do. Those are worth checking separately when a screen, message or summary can still look correct even though a change did not reach the place you intended.

Check that the deploy artifact contains static output and that backend functions run on their own supported service.

The site works locally where a development server handles a route that does not exist in the published build. Include this possibility when you define a failure. Try a known good case beside the suspected one. If both fail in the same way, examine what they share. If only the particular case fails, save the difference that makes it a useful test.

How to verify: Test the built output and use the default Pages URL before connecting a domain.

Choose how API or form links will work on the custom host. On the next pass, use a second representative input or condition to make sure the first result still applies. A narrow test can be decisive if it measures the thing you need. A wider sample is useful when your real work includes several distinct patterns and one result cannot stand for all of them.

Pick the final public name

The repository site will use the root or a subdomain such as docs.example.com. Before putting time or money into this step, agree on a concrete criterion. Treat whatever is essential to complete the job as a mandatory requirement. Keep convenience, speed and ease of handoff in a separate part of your notes. This helps you avoid promoting something that looks easier in a trial but cannot complete a critical part of the task.

Start here. Select the exact name and follow GitHub’s separate instructions for root, www and other subdomains. Note whether an alternate should redirect.

A record typed with the wrong label points only the wrong hostname at Pages. Think through how a customer or colleague would discover this error. A clear, visible failure is easier to resolve than a result that looks successful and leaves a problem for the next person. If it would be hard to notice, add one direct inspection that examines the outcome itself. Record evidence for the result instead of relying entirely on a successful status label.

Confirm the result. Check the target name independently in your authoritative DNS zone. Work through this step before expanding the change. One realistic example is enough to reveal a category of failures that an ideal example misses. A trial is also a useful time to learn what to do when the result is ambiguous, especially if different people would have to resolve disagreement.

Plan certificates and redirects for all publicly promoted entry names. Capture the decision and the reason in a short note so it can be revisited if the workload, policy or software changes.

Verify domain ownership

Example situation. The domain is being connected to an organization’s repository.

Use the ownership workflow for the intended GitHub account or organization. Add its exact TXT value and retain it as documented. Give the test enough room to show the original problem. Use the same entry point that someone with the issue would use. If several variables change between attempts, note which ones cannot be held constant and avoid assigning a cause yet. You can make a smaller experiment after getting that first picture.

The domain is assigned to a repo controlled under a different account than the one verified. It helps to document the specific contrast as soon as you see it. Save an innocuous screenshot, a small sample or a short time record if appropriate, with identifying details removed when they are unnecessary. The next person will need a result that can be interpreted without guessing what happened immediately before you captured it.

Inspect the outcome. Confirm verification in the correct organization’s settings and check the exact record. If you need to hand this to support or a maintainer, include the expected outcome, the first unexpected observation and the last known working state.

Separate registry ownership from GitHub verification in the team’s handover notes. Write down whether the follow-up confirms your original explanation or exposes another factor. Confirmed evidence supports a specific change. If the behavior still varies without a known reason, retain the last working settings and focus the next test on that variation.

Set DNS using current instructions

GitHub provides different records for an apex and subdomain. Decide what should stay intact while you try the change. For a small trial this might be the original input, a visible result another person already depends on, or access from a second supported device. Keep an appropriate copy or note of the earlier state. Tests that are easy to reverse make it possible to learn even when the first idea is wrong.

Use the values in current documentation. Preserve mail records and avoid wildcard entries that your intended setup does not require.

Watch for this: A copied article uses outdated addresses or a conflicting record in the active zone. Consider the exact point where you would stop and revert. If the issue appears, reproduce it without repeating a consequential action unnecessarily. A disposable example or read-only observation can give you the needed evidence. In a shared environment, tell others handling the test what state you expect to see before the next step.

Compare authoritative DNS with current GitHub documentation for the specific hostname. Verify the ordinary case that should have remained intact as well as the intended improvement. If one passes and the other fails, keep both observations and examine the relationship between them.

Check IPv6 and any alternate www address if the project intentionally supports them. Use the result to write a one-sentence acceptance condition. Make it specific enough that another person would know which setup to use and when to stop.

Confirm the publishing source

Pages is built by a GitHub Actions job or published from a branch.

Confirm the setting for the publishing source and understand how custom-domain configuration behaves in that workflow. Start with conditions you can readily repeat. Ask if your normal day includes a meaningful variation, such as a busy period, a second account or input from a different source. Select the variation based on your real use instead of trying every theoretical case.

A generated output step overwrites a domain file required by the branch workflow. Record whether you found a recurring failure, a one-time event or an unresolved observation. The three have different implications. A repeating mismatch is easier to verify and to pass along for repair. A one-time interruption can still matter, but document the context and look for a separate observation before committing to an explanation.

Trigger a test publish and inspect the settings and public response after deployment. A simple check for the result usually beats a complicated proxy. If a reading looks surprising, return to the user-visible outcome and trace it back to the earliest relevant event you can observe. Comparing that observation to the expected rule may show exactly what additional information to collect.

Keep the domain step in the runbook if a team member changes publishing methods. Use a representative size or repetition count when it affects the result. If a small test and a normal-sized workload behave differently, include both in the handoff so the earlier test can be understood in context.

Wait for HTTPS readiness

Use this case to review the plan. The domain resolves but the HTTPS option is unavailable.

Check the provider status and DNS configuration rather than changing unrelated records repeatedly. Enable enforcement after supported provisioning completes. Write down who owns the setting, file, service or decision before considering the trial finished. In a personal setup that may simply mean keeping the needed information somewhere you can find it later. In a shared setup it may determine whether the next person is able to continue during an interruption. Give that person enough context to determine if the result still applies.

Failure that matters: The domain reaches the correct host over HTTP but the certificate is not yet available.

Check the exact certificate name and a normal HTTPS load on the intended public address. A successful check has a concrete observable result. Confirm it from the normal user path, then put the test input and the observation in your notes. If cleanup is needed, remove test artifacts carefully and retain the benign evidence needed to repeat the test later.

Retest a background or stylesheet for mixed-content issues. Check any agreement about when to rerun the trial. An annual review can miss changes that happen at a specific release or after access is revoked. Conversely, some checks make sense on a fixed calendar because no individual event will remind you to try them. Choose the trigger that fits the use case and record a known starting point.

Fix asset and link bases

Try it when you need to: The original site lived under a repository path and now uses a custom root.

Update site configuration and absolute references so resources resolve correctly with the new base. Check navigation and share URLs.

Establish the expected result before starting. A useful way to make this concrete is to describe the one thing you plan to observe and the condition under which it should hold. Save a baseline using the same input or conditions you will use after the change. If another person helps, have them record the expected result independently. That can surface a difference in interpretation before you spend time debugging an apparent failure.

An easy mistake to miss: Only the homepage works because nested assets use a repository-prefix path that no longer applies.

Open a deep page from a fresh tab, then test navigation, images and download links. Preserve the comparison in a form you can come back to: write down the input, what you expected and what you actually saw. In a decision with several options, keep one record per option rather than changing the definition of success for each trial.

Inspect canonical and sitemap URLs after builds for consistency. Think about whether this follow-up calls for revising the original rule or handling a separate case. If it is separate, keep the original test available and check that both cases still succeed. This is also useful when you need to explain why something that looked fine in a demonstration behaves differently in ordinary use.

Plan cleanup and ownership

The organization later retires a Pages project. This is a good place to watch where the result starts to differ from what you expect. Note the entry conditions and any settings or data that you have assumed. Take an initial reading, then do the work with those same conditions recorded. Avoid resetting everything at the first sign of trouble. A change that accidentally hides the symptom gives you less information about what caused it.

Coordinate hosted settings and DNS removal. Keep domain records up to date and follow GitHub’s custom-domain security guidance.

Inspect this failure: The source project disappears while obsolete DNS continues pointing to the provider. Make the first follow-up test small enough to repeat without changing unrelated parts of the setup. Start at the first boundary you can observe, then check the next one only if the initial result was right. Write down the observations in order. A later symptom can look like the root problem if you check the later step first and do not have an earlier reading.

Confirm retirement according to the provider’s instructions and verify intended replacement routing. When the check is successful, repeat the ordinary action from its normal starting point. This catches results that only worked because the original test left a session, a temporary setting or a sample file in place. If somebody else follows the directions later, their starting conditions might be different.

Record who can review the domain list during renewals or project handoffs.

A short verification checklist

What to checkHow to tell
Confirm GitHub Pages fits your siteTest the built output and use the default Pages URL before connecting a domain.
Pick the final public nameCheck the target name independently in your authoritative DNS zone.
Verify domain ownershipConfirm verification in the correct organization’s settings and check the exact record.
Set DNS using current instructionsCompare authoritative DNS with current GitHub documentation for the specific hostname.

## Handle the publishing branch and build carefully
GitHub Pages can publish from supported build configurations. When the change includes a custom domain, follow guidance for the actual publication source. Preserve any domain configuration specific to a branch-based workflow if a build regenerates the files in that branch. Record the owner that verified the domain and the configured address. Test the assets and links at the deployed address from a fresh session. Validate the repository path and final base URL independently because a static site generator may infer them differently. Keep the verification record described in GitHub’s current instructions.

Related reading

Reference documentation explains the relevant standards or workflow. Try the related FixHubLab resource for a practical next step. Use the FixHubLab blog to find the rest of the guide series.