Beginner
How to connect a GitHub repository on Netlify
Quick Answer
Link your GitHub repo to Netlify via the dashboard under Build & deploy for automatic deploys on git push. Authorize the Netlify GitHub App, select your repo, and configure build settings like branch, build command, and publish directory. Troubleshoot common OAuth or permission issues by revoking/re-authorizing apps and clearing browser cache.
Prerequisites
- Netlify account logged in at app.netlify.com
- GitHub account with a repository ready (public or private)
- Admin access to the GitHub repo
- Browser with JavaScript enabled (Chrome/Firefox recommended)
- Repo pushed to deploy branch like main or master
1
Log into Netlify dashboard
Log into your Netlify dashboard at
app.netlify.com and select the target site from your Sites list. For a new site, click Add new site > Import an existing project.2
Navigate to Continuous deployment
In the site's overview page, go to Project configuration (left sidebar) > Build & deploy > Continuous deployment. Scroll to the Repository section and click Link repository.
3
Select GitHub provider
On the provider selection page, click the GitHub icon. If not already installed, you will be prompted to authorize and install the Netlify GitHub App.
Tip
Grant access to all repositories for simplicity or specific ones only.
4
Authorize Netlify GitHub App
Grant the required scoped permissions (read access to repo contents, metadata, webhooks). Authorize Netlify on GitHub's side. Select your GitHub repository from the filtered list. If missing, click Configure Netlify on GitHub to adjust permissions.
Tip
Ensure you have admin access to the repo or org-level permissions.
5
Configure deployment settings
Set the Branch to deploy (default:
main), Base directory (default: /), Build command (e.g. npm run build for React/Vite or empty for static), and Publish directory (e.g. dist or build).Tip
Match settings to your framework; for submodules/private repos use deploy keys.
6
Handle private repos with deploy keys if needed
For private repos or submodules needing SSH: Go to the Deploy key tab, click Generate public key, then add the public key to your GitHub repo settings as a deploy key.
7
Deploy and link site
Scroll down and click Deploy or Link site. Netlify will trigger an initial deploy. Future
git push to the linked branch will auto-deploy.Tip
Verify the deploy succeeds in the Deploys tab.
8
Alternative: Create new site from GitHub
From Netlify dashboard, click Add new site > Import an existing project > GitHub, authorize app, select repo, configure settings, and click Deploy site.
9
CLI method setup
Install Netlify CLI with
npm install netlify-cli -gbrew install netlify-cli on macOS. Run netlify login to authenticate, then from your local repo directory use netlify init to link.Tip
CLI is great for local testing and automation.
Troubleshooting
"Verification Failed", "We already have a registered user with this email", or "Your account requires additional verification"
Log into Netlify with email/password (reset if needed). Go to Netlify Settings > Connected Accounts, disconnect GitHub. Clear browser cache/cookies, retry in incognito. In GitHub Settings > Applications > Authorized OAuth Apps, revoke Netlify and re-authorize.
Repository not listed or permission denied
Verify repo admin access. In GitHub, adjust Netlify GitHub App permissions to include the repo (all repos or specific). Use Link to a different repository option in Netlify.
Deploy fails on private repo/submodules
Generate and add Netlify deploy key to GitHub repo settings > Deploy keys. Ensure SSH access for private repos.
OAuth token conflict or stale auth
Revoke Netlify apps in GitHub settings, log out everywhere, clear browser cache, and re-authorize using incognito mode.
Build settings mismatch causing deploy failure
Double-check branch name, build command (e.g.
npm run build), and publish directory (e.g. dist) match your project structure.Ready to get started with Netlify?
Put this tutorial into practice. Visit Netlify and follow the steps above.
Visit Netlify →