How to Set Up Custom Domain for GitDocAI: Complete Guide
Learn how to set up custom domain for your GitDocAI docs site. Step-by-step CNAME, apex, Cloudflare SSL setup with troubleshooting tips.
You’ve added the custom-domain record, entered the GitDocAI target, and activated the hostname in the dashboard. Yet the browser still shows a certificate warning, the verification check keeps timing out, or visitors are landing on the old documentation address. Launch day is close, and the DNS screen says everything is correct.
That situation is common because a custom domain is not one setting. It’s a chain involving DNS records, resolver caches, hostname verification, certificate issuance, CDN behavior, and redirects. A reliable setup separates those layers, chooses the domain strategy before records are changed, and gives each system enough time to complete its work.
Table of Contents
- Why Custom Domain Setup Fails And How To Avoid It
- Setting Up CNAME for Your Documentation Subdomain
- Apex Domain Versus Subdomain Strategy
- SSL Verification and Cloudflare Integration
- Troubleshooting Common Domain Configuration Errors
- Advanced Configurations for Multi-Version Docs
Why Custom Domain Setup Fails And How To Avoid It
A launch can look correct in the DNS console while readers still see the old documentation site, a certificate warning, or a verification timeout. DNS caches, platform ownership checks, certificate issuance, and CDN behavior complete on different schedules. Treating the change as one instant switch is the usual cause of confusion.
For a planned custom-domain launch, lower the record TTL to about 300 seconds 24 to 48 hours before the change. Public resolvers may refresh in 15 to 60 minutes, while many ISP resolvers in major markets take 1 to 4 hours. Broad global completion typically takes 2 to 8 hours, although caches honoring longer TTL values can create a theoretical maximum near 48 hours, as described in this DNS propagation playbook.
Decide between a subdomain and an apex domain
For a documentation site, begin with a subdomain such as docs.company.com. It can use a standard CNAME, keeps the application domain separate, and gives the documentation platform a straightforward hostname to validate. That approach also reduces dependence on DNS-provider-specific features.
An apex domain, such as company.com, has a structural limitation. The root already contains authoritative records such as SOA and NS, so it cannot use a plain CNAME. Use ALIAS or CNAME flattening where the DNS provider supports it, direct address records supplied by the platform, or an apex redirect to a canonical hostname such as www. The technical guide to the CNAME-at-apex limitation explains why this choice matters.
Use a controlled sequence
Choose the canonical hostname before changing records. Check certificate coverage for that hostname and for any hostname that will redirect to it. Publish the DNS change, wait at least the old TTL period, activate verification in GitDocAI, and test from more than one network.
Keep redirects short and predictable. A chain from apex to HTTP www, followed by HTTP www to HTTPS www, adds latency and complicates certificate validation. The failures that need attention are usually an incorrect target, an unsupported apex record, a proxy conflict, or a certificate that excludes the requested hostname. A stale browser cache can hide a successful change, but it does not indicate broken DNS.
Setting Up CNAME for Your Documentation Subdomain
The CNAME route is the practical default for a branded documentation site. It keeps your primary application domain separate, gives the documentation platform a clear hostname to validate, and avoids the apex limitation described earlier.
Add the hostname in the platform first
Open the custom-domain area in the GitDocAI dashboard and enter the hostname you want readers to use, for example docs.company.com. The dashboard will provide the target hostname assigned to your documentation site. Copy that value exactly. Don’t replace it with a guessed hostname or a target copied from another project.
The platform-side entry and the DNS record serve different purposes. The dashboard tells GitDocAI which hostname belongs to the site, while your DNS provider tells browsers where that hostname should resolve. Both must agree character for character.
Create the CNAME record
In your DNS provider, create a CNAME record with:
- Host or name:
docs - Type: CNAME
- Value or target: the exact GitDocAI-assigned hostname
- Proxy setting: DNS only while validation and certificate issuance are taking place
Cloudflare usually labels the proxy choice as DNS only or proxied. Route 53 presents the record through its hosted-zone interface, while Namecheap uses its Advanced DNS panel. The field names differ, but the underlying record relationship is the same. Remove an older conflicting record for the same hostname before saving, especially if an A record already exists for docs.
If your team also maintains repository-driven content, keep the domain work separate from your publishing workflow. Git-based updates and domain configuration have different failure modes, so document the change alongside your deployment process in GitDocAI’s GitHub synchronization guidance.
Configuration rule: Keep the DNS record on DNS only during certificate validation. A conflicting CDN or proxy rule can intercept the request and prevent the platform from completing its SSL handshake.
Verify the hostname
Once the record is saved, return to the GitDocAI dashboard and start or refresh verification. The system checks whether the hostname resolves to the expected target and can then begin certificate provisioning. Cloudflare for SaaS handles the automatic SSL process for supported custom hostnames, but DNS visibility still has to reach the validating systems first.
Test the hostname in a private browser window after propagation begins. If it resolves but HTTPS is not ready, don’t repeatedly edit the record. Confirm the target, check the proxy mode, and allow the certificate process to finish. Teams working with several branded developer portals can also compare this flow with guidance on linking custom domains to agents, particularly when a platform needs to associate customer-owned hostnames with separate services.
Apex Domain Versus Subdomain Strategy
A documentation migration can appear successful while the root domain, www host, and documentation hostname behave differently. Choose the public hostname before changing DNS, because that decision affects record support, certificate coverage, redirects, and how a multi-tenant platform separates customer sites.
A subdomain, such as docs.company.com, is usually easier to operate. A standard CNAME can point it to the documentation platform, which can request a certificate for that exact hostname. An apex domain, such as company.com, gives users a shorter address, but the DNS provider must support ALIAS, ANAME, flattening, direct address records, or a comparable method. A plain root CNAME is not valid because the apex must retain its authoritative SOA and NS records.
| Factor | Subdomain, docs.company.com | Apex, company.com |
|---|---|---|
| DNS record | Standard CNAME is usually available | Requires ALIAS, flattening, direct address records, or redirect design |
| Certificate coverage | Validate the documentation hostname directly | Validate the root and any redirect destination |
| CDN compatibility | Usually straightforward | Depends on provider support for apex flattening or equivalent |
| Redirect needs | Optional, depending on your preferred hostname | Often redirects to www or another canonical host |
| Provider requirements | Lower | Higher and provider-specific |
| Operational risk | Fewer moving parts | More interaction between DNS, redirects, and SSL |
Choose the canonical host before editing records
Set docs.company.com as canonical if that is the address users should bookmark. Redirect alternate hosts directly to it. If the brand requires company.com, verify the provider’s apex support before editing the live zone. Treat the redirect target as part of the design, not as a later cleanup task.
Certificate scope must match every hostname users can reach. A certificate for docs.company.com does not automatically cover company.com or www.company.com. List the intended names in the platform configuration, then make each redirect point to the final HTTPS hostname.
Avoid multi-hop routing
An apex redirect is practical when the root cannot point directly to the documentation service. Use one direct redirect to the canonical HTTPS host. Sending visitors through an HTTP version first adds a request and can interfere with certificate validation or create confusing browser errors.
For a multi-tenant documentation service, subdomains also create cleaner ownership boundaries. Each customer hostname can be validated, issued a certificate, monitored, migrated, or removed independently. That separation limits the blast radius when one customer changes DNS or a certificate renewal fails. Apex setups can work, but they usually require tighter coordination between the DNS provider, redirect layer, CDN, and platform configuration.
SSL Verification and Cloudflare Integration
DNS answers the question, “Where should this hostname go?” SSL answers a different question, “Is this service authorized to serve HTTPS for this hostname?” A domain can resolve correctly and still fail because the certificate hasn’t been issued, hasn’t propagated to the edge, or doesn’t include the requested name.
Understand the validation path
After the CNAME becomes visible, GitDocAI’s custom-hostname layer can validate the association and Cloudflare for SaaS can manage certificate provisioning for the hostname. The process depends on the platform seeing the expected DNS answer and reaching the correct origin or validation endpoint.
A proxy changes that path. With DNS only, the validating service sees the direct CNAME relationship. With a proxied record, Cloudflare sits between the visitor and the platform, which can be useful in a mature architecture but can also obscure the expected response during initial validation.
Use this diagnostic sequence:
- Target check: Confirm that the CNAME value exactly matches the target shown in the GitDocAI dashboard.
- Proxy check: Temporarily use DNS only while validation is pending.
- Hostname check: Make sure the requested URL matches the hostname entered in the platform.
- Certificate check: Confirm that the certificate covers the exact name, not merely the parent domain.
- Timing check: Allow DNS and certificate propagation to complete before making another change.
Operational insight: DNS verification, certificate issuance, and CDN routing are separate states. A green result in one layer doesn’t prove that the other two are ready.
Once HTTPS works, review the final proxy and SSL/TLS settings deliberately. Don’t switch modes repeatedly while the certificate is pending. If the site is private, test both the unauthenticated response and the authenticated flow, because a CDN or access rule can behave differently for each.
Before a production launch, also align the domain change with your release process. A documented rollback and a known publishing owner are more useful than repeated manual edits, especially when the documentation site changes alongside an application release. GitDocAI’s CI/CD best-practices guidance can help teams keep publishing and operational checks in one workflow.
Troubleshooting Common Domain Configuration Errors
A custom domain can look healthy in one browser and fail for another tenant or network. Diagnose the layer first. The visible error may come from DNS, SSL, proxy routing, or redirects, and changing records before identifying that layer often creates a second problem.
The old site still appears
If the browser shows the original GitDocAI subdomain, test in a private window and from another network. A different result usually points to a stale resolver cache rather than an incorrect record. Check the hostname used by each tenant, because one cached response can make a migration appear inconsistent.
For a planned cutover, lower the TTL before changing the record, wait through the previous TTL period, then publish the new target. Follow the documented DNS propagation sequence by verifying the new A, AAAA, or alias target and restoring a normal TTL after traffic stabilizes. Avoid repeated edits while caches converge. Each change makes the result harder to interpret.
The certificate reports a hostname mismatch
NET::ERR_CERT_COMMON_NAME_INVALID means the certificate presented to the browser does not cover the requested hostname. Check for a typo in the CNAME target, an old certificate at a proxy layer, or a request reaching a service other than the one configured in GitDocAI.
Temporarily set the record to DNS only, confirm the platform hostname, and allow certificate provisioning to finish. If the error persists, inspect the certificate for the exact documentation hostname, such as docs.company.com. A certificate covering only the root or another subdomain will not resolve the mismatch.
The apex record won’t save
If a provider rejects a CNAME at company.com, that is a provider constraint, not a GitDocAI outage. Use ALIAS or flattening when supported, publish the provider’s supported direct records, or redirect the apex to one canonical www or documentation hostname. The apex-domain guidance explains the root-domain limitation and why the canonical host should be selected before setup.
Redirect loops need a separate review. Check HTTPS mode at every layer, identify which service terminates TLS, and ensure the origin is not forcing HTTP while the edge requires HTTPS. Send the request to one canonical destination without chaining several intermediate URLs.
Advanced Configurations for Multi-Version Docs
A working custom domain is only the beginning for a documentation platform serving evolving products. Teams soon need to decide how versioned content, private access, deleted projects, and hostname changes should behave. Those decisions belong in the domain design, not as emergency fixes after launch.
Select a versioning model
Path-based versioning, such as docs.company.com/v2, keeps one hostname and makes the relationship between versions visible. It can simplify branding and certificate management, but redirects and navigation must preserve the selected version when a page moves.
Subdomain isolation, such as v2.docs.company.com, separates versions more strongly. That can help teams apply distinct release controls, but every additional hostname introduces another certificate, DNS, and monitoring surface. Choose it when the versions need different operational boundaries, not merely because the URL looks tidy.
For API products, define the status of each version clearly, such as latest, supported, or deprecated. Keep canonical links and navigation consistent so users and search engines don’t encounter multiple URLs for the same content. GitDocAI’s API documentation versioning guidance provides a useful reference for structuring version-aware documentation.
Treat authentication as part of routing
Private documentation adds an access layer to the hostname. Decide whether the custom domain serves an internal knowledge base, a customer portal, or a hybrid experience. Then test login redirects, callback URLs, session cookies, and deep links from an unauthenticated browser.
Role-based access should match the documentation workflow. Editors may need to review generated changes, while readers should only reach published content. For customer portals, verify that a user authenticated for one tenant can’t access another tenant’s pages through a copied URL.
Plan hostname lifecycle management
Multi-tenant platforms need repeatable handling for provisioning, certificate issuance, rollback, migration, and deletion. Cloudflare’s SaaS custom-hostname documentation covers custom hostnames, TLS selection, validation methods, custom origins, and hostname migration. Those capabilities highlight an operational reality: the difficult part isn’t only adding the first CNAME, it’s keeping customer-owned domains reliable over time.
When a project is deleted, define whether its hostname returns an error, redirects to a replacement, or enters a controlled retirement state. When a customer changes domains, provision the new hostname before removing the old one, preserve intentional redirects, and keep a rollback path until traffic has moved successfully. Document every state in your runbook so support doesn’t have to infer what happened from a single browser error.
GitDocAI turns GitHub repositories, API specifications, uploaded files, crawled sites, and product descriptions into branded documentation sites that can stay synchronized with repository changes. It supports custom domains with automatic SSL, public or private access, versioned documentation, RBAC, and reviewable AI-assisted updates. Visit GitDocAI to configure a documentation site around your domain and deployment workflow.