Move a GitHub Pages Website to Netlify

Keep the Repository, Change the Host

You can move a static GitHub Pages website to Netlify and keep its GitHub repository. Connect the same repository to Netlify. Reproduce the build there. Test the new address. Only after that, move the custom domain.

GitHub stays your place for version control and pull requests. Netlify takes over the build and the hosting of the files. Common reasons to move are preview links for every pull request and redirect rules with real HTTP status codes. Other reasons are built-in form handling and password protection on paid plans. Some people also need build tools that the default Jekyll setup of GitHub does not support.

GitHub Pages and Netlify After the Move

Need	GitHub Pages	Netlify
Store and review site files	GitHub repository, commits, and pull requests	The same repository, connected to Netlify
Build the site	Deploy from a branch, or run a GitHub Actions workflow	A build command and publish directory, run on every push
Preview changes	GitHub’s starter workflows deploy only from the default branch	A Deploy Preview for each pull request, at an address such as deploy-preview-42--yoursite.netlify.app
Redirect old URLs	The jekyll-redirect-from plugin, which writes HTML refresh pages	A _redirects file or netlify.toml rules
Collect form responses	A separate form service	Netlify Forms
Restrict visitors	Private visibility requires GitHub Enterprise Cloud	Password protection on Pro plans and above

Before You Migrate

Make sure that the site is static. A static site has only HTML, CSS, JavaScript, images and other files that a browser can open. Server-side code, databases and long-running processes need a different hosting setup.

Then write down how GitHub builds and serves the site today. In the repository, open Settings > Pages. Look under Build and deployment > Source (GitHub’s publishing source docs).

If the source is Deploy from a branch, note the branch and the folder. The folder is either the root (/) or /docs. If that folder has a _config.yml file, Jekyll builds the site. If it has a .nojekyll file, GitHub serves the files as they are.

If the source is GitHub Actions, open the workflow in .github/workflows/. Note the build command. Also note the folder that the workflow uploads as the Pages artifact (the files that GitHub Pages publishes).

Also write down these details:

• The current address: <owner>.github.io, <owner>.github.io/<repository> for a project site, or a custom domain.
• Any baseurl setting or absolute paths that include the repository name.
• Redirects, a custom 404.html, and form scripts or analytics scripts in the pages.
• The current DNS records for the custom domain, so that you can roll back.

1. Reproduce the Build Locally

Before Netlify builds the site, build it on your own machine. The steps depend on the type of site:

• For plain HTML, there is nothing to build. The publish directory (the folder that Netlify serves) is the root folder or the docs/ folder that you noted.
• For Jekyll, GitHub Pages uses its own pinned (fixed) versions of each tool. The dependency versions page lists them. If the repository has no Gemfile, add one. The Gemfile must use the github-pages gem or pin the same Jekyll version, so that the result matches. Run bundle exec jekyll build. Then make sure that the _site folder contains the site.
• For a different site generator in GitHub Actions, copy the build steps from the workflow, such as npm ci and npm run build. Note the output folder.

If the old address was a project site, the build probably uses a base path such as /<repository>. Netlify serves the site from the root of its own domain. So clear baseurl or the equivalent setting in your generator. Then fix any hard-coded paths that include the repository name.

2. Connect the Repository to Netlify

The Netlify add new project guide shows these steps:

1. On the Projects page of your team, open Add new project. Select Import an existing project.
2. Choose GitHub. Authorize Netlify for the account or the organization that owns the repository.
3. Select the repository and the branch that you deploy from.
4. Make sure that the Build command and the Publish directory are correct. If Netlify recognizes the framework, it fills in these fields. If a value is wrong, correct it. For Jekyll, the values are usually bundle exec jekyll build and _site.
5. Select Deploy site.

Instead, you can keep these settings in a netlify.toml file at the root of the repository:

[build]
  command = "bundle exec jekyll build"
  publish = "_site"

Netlify uses Bundler to install the Ruby gems from the Gemfile. You can pin the Ruby version with a .ruby-version file (build dependencies). After this setup, every push to the branch starts a new production deploy.

3. Test on the Netlify Address

Open the netlify.app address that Netlify assigned. Compare these items with the live GitHub Pages site:

• The home page and every nested page, including direct visits to nested URLs.
• Images, styles, scripts, fonts, and downloads.
• The custom 404.html page.
• Letter case in file names and links.
• Files and folders whose names start with _. Jekyll leaves them out unless the configuration of the site includes them.

4. Replace GitHub-Only Pieces

For redirects, Netlify reads a plain-text _redirects file from the publish directory (redirect docs). Each line holds the old path, the new path and an optional status code:

/old-page/   /new-page/   301

Jekyll leaves out files whose names start with _. So add _redirects to the include list in _config.yml.

If a form sends its data to a third-party service, the form can keep working. To use Netlify for forms instead, go to Forms. Select Enable form detection. Then add data-netlify="true" and a name attribute to the <form> tag. Set up email alerts under Forms > Submission notifications.

If privacy is a reason for the move, set up password protection before you push confidential material. A private repository does not make the hosted site private on either service.

5. Move the Custom Domain

Keep the GitHub Pages site online until the Netlify version passes every test above. Then do these steps:

1. Add the domain in Netlify first. Netlify shows the DNS records that it needs under Domain management > Production domains (external DNS guide).
2. Update the DNS at your provider. For a subdomain such as www, point a CNAME record at your netlify.app address. The apex domain is the domain without a subdomain. For the apex domain, use an ALIAS, ANAME or flattened CNAME record that points to apex-loadbalancer.netlify.com. If your provider has none of those record types, use the A record that Netlify documents. If you add the apex or www, Netlify adds both. So set up both records.
3. Wait for the DNS change. DNS changes can take several hours, and up to a day, to spread. Before you change anything on GitHub, test the apex and www over HTTPS.
4. Remove the domain from GitHub Pages. In the repository, open Settings > Pages. Under Custom domain, select Remove (custom domain docs).
5. If you no longer need the old site, unpublish it (unpublishing steps).

Do these steps in this order. After the site is gone, make sure that no DNS records point to GitHub. GitHub warns that a disabled Pages site with a custom domain still configured is at risk of a domain takeover. In a domain takeover, another person publishes a site on your domain.

If the old site had only a github.io address, that address stays with GitHub. To send visitors to the new address, you have two options. Keep Pages running from a separate branch that holds only redirect pages. The redirect_to key of the jekyll-redirect-from plugin creates these pages. Or leave a short page that links to the new address.

Keep Working in GitHub

The move does not change how you edit the site. Developers still commit and open pull requests in GitHub. Netlify builds a Deploy Preview for each pull request. Reviewers can then see the change on a real URL before it merges. The next push to the production branch updates the live site.

If you also want to use the command line, the Netlify CLI can link the local folder to the same project (netlify link). It can also create draft deploys from your machine (CLI guide).

Migration Checklist

Before you finish, make sure that these statements are true:

• You wrote down the build source, the branch, the folder and the current DNS records.
• The site builds locally with the same command that Netlify runs.
• Netlify has the right build command and publish directory.
• Every page, asset, download, and the 404 page work on the netlify.app address.
• You moved the redirects, the forms and the access settings.
• You added the custom domain in Netlify before you changed the DNS.
• After the change, the apex and www both load over HTTPS.
• You removed the custom domain from GitHub Pages, and no DNS records still point to GitHub.

If you still have to choose a host for a new site, compare both options. You can publish on GitHub Pages or Netlify from the start.

A docs portal with Ask AI
and support tickets

Connect a repository, or describe your product to start. Each docs site has search, Ask AI, an API console, an MCP server and support tickets.

• Publishes from GitHub on every push
• Works with Mintlify repositories
• API console from your OpenAPI file
• MCP server and llms.txt for AI agents
• Ask AI and support tickets
• Analytics for people and AI agents

Start Free→ Questions? Ask AI in our docs

No card required.