How to deploy a GitHub website to Netlify

Before you start

You need the site’s code in a GitHub repository you control and a Netlify account of your own. If the repository isn’t yours yet, start with putting your website’s code in GitHub. If you’re moving from another host, leave it running; the domain changes last.

Step 1: Know what kind of site it is

Netlify detects the framework from the repository and proposes build settings, so you don’t need to name it. What you do need to know is whether the site is a static set of pages or has a server side (sign-in, saved form data, a database), because that decides what to test and which environment variables exist. Look at package.json on GitHub for the framework name, and for an .env.example file listing variables. The secrets guide explains how to build the full list.

Step 2: Import the repository

1. In the Netlify dashboard, choose Add new project, then Import an existing project.
2. Choose GitHub. Netlify installs its GitHub App; when GitHub asks which repositories to allow, pick only the ones Netlify should see.
3. Select the repository. Netlify shows the branch it will deploy from and the build settings it detected. The button that starts the first build is labelled Deploy site.

Step 3: Base directory and build settings

Netlify’s build settings have four parts: the base directory, the build command, the publish directory, and, for sites with server functions, the functions directory. For most single-app repositories the detected values are right. Change them only in these cases:

• The repository holds more than one app. Set the base directory to the folder containing the website’s package.json. Netlify runs the build from there.
• Detection is wrong. Netlify’s framework documentation lists the build command and publish directory for each framework; use those values, or ask a developer or your coding agent.
• The site needs a particular Node version. Netlify reads it from an .nvmrc file in the repository or from a NODE_VERSION environment variable. A build that fails with an unrecognised syntax error usually wants a newer Node.

A failed first build is normal and costs nothing. Read the deploy log before changing settings.

Step 4: Environment variables

Under the project’s environment variables, add each one the site needs. Netlify can import them from a .env file if a developer gives you one, or you enter them by name and value. For real secrets, tick “Contains secret values” so they become write-only; you can replace them later but never read them back. Netlify recommends keeping sensitive values here rather than in the repository’s netlify.toml file.

Step 5: Deploy and test on the netlify.app address

Click Deploy site. Netlify assigns a project name and an address your-project-name.netlify.app; renaming the project changes the address. That address keeps working even after a custom domain is attached, which makes it the place to test. Test it as a visitor would:

From now on every push to the production branch deploys, and pull requests get deploy previews with their own addresses.

Step 6: Add the domain

Under Domain management, add the custom domain. Netlify offers two routes: Netlify DNS, which means changing your nameservers, and which Netlify’s own docs mark as its recommended option; or external DNS, which means adding records at the provider you already use. For a domain that already carries email or other records, the external route is the safer one, because nothing else moves; Netlify itself notes that it can’t import an existing DNS zone, so a domain with many records is easier to leave where it is. Netlify’s records for external DNS:

• For the bare domain, an ALIAS, ANAME or flattened CNAME to apex-loadbalancer.netlify.com if your DNS provider supports one, otherwise an A record to 75.2.60.5.
• For www, a CNAME to your site’s netlify.app address.

Add either name and Netlify adds the other automatically. Set one as the primary domain; Netlify redirects the other to it, and on external DNS it recommends making www primary, because the bare domain’s A record can’t use its global network the way the CNAME can. There’s no verification TXT record; Netlify checks the website records themselves and shows the domain as pending until they resolve. If you do choose Netlify DNS, Netlify’s own instructions say to copy your existing records, including MX records for email, into Netlify DNS before changing nameservers. Either way, the guide to connecting a domain without breaking email has the capture, TTL and verification steps.

Step 7: HTTPS

Netlify provisions a Let’s Encrypt certificate automatically once the domain’s DNS points at it, and renews it. DNS has to be in place first, for every name on the certificate, so the bare domain and www both need their records before it will cover both, and Netlify notes that old DNS settings must have expired from caches first. If the certificate doesn’t appear after that, the domain settings have a Renew certificate option that retries. One more thing Netlify is explicit about: if the domain is proxied through Cloudflare, that proxying has to be turned off before Netlify can issue the certificate. Then confirm both addresses load over https and run the email checks.

Later: pushes, rollbacks and leaving

• Every push to the production branch builds and publishes. Netlify’s deploys are atomic: nothing goes live until the whole build has uploaded.
• If a push doesn’t show up on the site, the guide to a website not updating after a deploy traces the change from the edit to the browser; for domain and certificate problems after step 6, see website not showing after a DNS change and HTTPS not working.
• Rolling back: open Deploys, pick an earlier successful deploy and choose Publish deploy. It’s instant. Note that with auto-publishing on, the next push will overwrite the rollback; Netlify lets you stop auto-publishing to hold a deploy in place.
• Adding people: team members with roles, including one for people who only push code. See the access guide.
• Leaving: follow the host move guide, change the two DNS records, then remove the domain, unlink the repository under Build & deploy, and delete the project from the Danger zone in its configuration, which only a team Owner can do. If the site used Netlify Forms, submissions were being collected by Netlify at deploy time, so the form needs a new destination before you go; if it used Netlify DNS, the zone needs recreating at another provider before the nameservers change.

Checklist

Sources

The rules and product behaviour described above were checked against these pages when the guide was last updated. If something here has changed, these are the places to look.

• Add a new project · Netlify
• Repository permissions and linking · Netlify
• Build configuration overview · Netlify
• Manage build dependencies · Netlify
• Get started with environment variables · Netlify
• Secrets controller · Netlify
• How projects work · Netlify
• Understand domains · Netlify
• Get started with domains · Netlify
• Configure external DNS for a custom domain · Netlify
• Manage multiple domains · Netlify
• Set up Netlify DNS · Netlify
• HTTPS (SSL) · Netlify
• Domain troubleshooting tips · Netlify
• Manage deploys · Netlify
• Disable projects · Netlify
• Forms setup · Netlify