What is the Netlify GitHub integration and how does it work

How Do You Connect GitHub to Netlify Step by Step?

Where Does Netlify GitHub Integration Break Down?

Netlify Only Deploys Static Output

Build Minute Caps Hit Fast on Free Tier

Full-Stack Frameworks Require Specific Plugins

OAuth Token Breaks on Repo Permission Changes

Build-Time vs Runtime Environment Variables Behave Differently

How to Fix the Most Common Netlify GitHub Integration Errors

When Netlify GitHub Integration Is Not Enough, Use Kuberns

How Kuberns GitHub Integration Compares to Netlify

Conclusion: GitHub Integration That Works Beyond the Frontend Netlify’s GitHub integration connects your repo and auto-deploys on every push in minutes. For static sites and frontend-only projects, it works exactly as advertised. For full-stack apps, the integration hits its limits quickly, and those limits are not always obvious until you are already in production. This guide covers how the Netlify GitHub integration actually works, how to connect it step by step, the specific points where it breaks down, the most common errors and how to fix them, and what to use when Netlify’s GitHub integration is not enough for your project. What Is the Netlify GitHub Integration and How Does It Work? The Netlify GitHub integration is a continuous deployment pipeline that connects a GitHub repository to a Netlify site. When you push to the configured branch, Netlify clones the repo, runs your build command, and publishes the static output to its CDN. No manual uploads, no FTP, no re-triggering deployments from a dashboard. There are two ways Netlify connects to GitHub: OAuth2 authentication grants Netlify access to your repositories using a personal access token. It is the default method and the quickest to set up. The drawback is that if you rotate your GitHub token or change account permissions, the connection breaks silently. The Netlify GitHub App uses installation-level, scoped permissions rather than a personal token. It is more secure, more granular, and does not break when personal tokens change. For any team environment, this is the connection method worth using. Once connected, Netlify listens for push events via a GitHub webhook. Every push to the production branch triggers a new build. Every pull request generates a Deploy Preview: a unique live URL at branch-name--your-site.netlify.app where you can review changes before merging. Branch deploys let you run separate builds for staging or feature branches. The key thing to understand is what Netlify actually deploys: the static output of your build command. Netlify does not run a server. It publishes files. That distinction is what makes the integration work seamlessly for frontend projects and creates hard blockers for anything that needs a persistent backend process. To understand exactly what Netlify hosting covers and where it stops, that guide breaks down the platform’s actual deployment model in detail.

_** Step 1: Create a new site from Git. In your Netlify dashboard, click Add new site, then Import an existing project. Select GitHub as your Git provider. Step 2: Authorize Netlify. GitHub will prompt you to authorize the Netlify GitHub App or OAuth connection. For team repos, choose the GitHub App and install it on the specific organization or repository rather than granting access to all repos. Step 3: Select your repo and branch. Pick the repository and the branch you want as your production branch. This is the branch Netlify watches for pushes. Typically main or master. Step 4: Configure build settings. Netlify auto-detects frameworks in most cases. If it does not, here are the correct settings by framework: Step 5: Add environment variables. Under Advanced build settings, add any environment variables your build needs. Variables added here are available during the build process. Do not confuse these with runtime environment variables for Netlify Functions, which are configured separately. Step 6: Deploy. Click Deploy site. The first deploy takes 2 to 5 minutes. Subsequent deploys are faster because Netlify caches dependencies. Every push to the production branch triggers a new deploy automatically from this point forward. For advanced configuration, add a netlify.toml file to the root of your repo: Note: settings in netlify.toml override dashboard settings silently. If your dashboard config is not taking effect, a netlify.toml file in the repo is likely overriding it. For teams connecting custom domains after their first deploy, see how to add a custom domain to a deployed app without DNS misconfiguration._** The setup works. The problems surface later, usually in production, when the project grows beyond a simple frontend build. Netlify runs your build command and publishes the output. It does not run a server process. If your app has a Node.js, Python, Go, or any other backend, Netlify does not deploy it. This is not a configuration problem. It is a fundamental constraint of how Netlify works. Netlify Functions offer a workaround for simple serverless logic, but they come with hard limits: 10-second execution timeout on the free tier, 26 seconds on Pro. No WebSockets. No persistent connections. No background jobs. For any API that needs to handle database connections, stream data, or run long operations, Netlify Functions are not a substitute for a real backend. See whether you can actually deploy a backend on Netlify for a complete breakdown. Netlify’s free tier includes 300 build minutes per month. A typical React or Next.js build takes 2 to 4 minutes. That gives you roughly 75 to 150 deploys per month before hitting the cap. For teams deploying on every PR and every push to main, the free tier runs out in the first week. Next.js App Router, Nuxt 3, and SvelteKit are not static-output frameworks. They require server-side rendering, API routes, and edge functions. Netlify supports these through adapter plugins, but not all features are covered. Next.js App Router support on Netlify is partial, with some features like Incremental Static Regeneration and certain middleware behaviours requiring workarounds or simply not working. The full picture of deploying Next.js on Netlify covers exactly which features are supported and which are not. If you use the OAuth connection method and later change repository access in GitHub (transferring a repo, changing org permissions, or rotating tokens), Netlify loses access silently. The site dashboard shows no error until the next push fails to trigger a deploy. Switching to the Netlify GitHub App avoids this because permissions are scoped to the installation, not a personal token. Variables added in Netlify’s build settings are injected at build time and baked into the static output. They are not available at runtime in Netlify Functions unless explicitly added to the Functions environment configuration. This catches teams out when API keys added to the dashboard do not appear available in their serverless function logs. Netlify’s pricing tier determines your build minute allowance, function execution limits, and team seat costs. Worth reviewing before you scale._** Deploy not triggering after a push. Check that the branch you pushed to matches the production branch in Site Settings > Build and Deploy > Continuous Deployment. Then go to your GitHub repo Settings > Webhooks and confirm the Netlify webhook shows a green tick on recent deliveries. If the webhook is failing, delete it and reconnect the repo from Netlify. Build failing immediately after connecting. The most common causes are a missing lockfile (package-lock.json or yarn.lock not committed), a Node version mismatch, or a wrong publish directory. Check the deploy log for the exact error line. Set the correct Node version in Site Settings or via NODE_VERSION in your netlify.toml. Private repo showing as not found. The OAuth token does not have access to the repo. Go to GitHub Settings > Applications > Authorized OAuth Apps, revoke Netlify’s access, then reconnect from your Netlify site settings. Better long-term fix: switch to the Netlify GitHub App which uses installation-scoped permissions. netlify.toml overriding dashboard settings. A netlify.toml file in the repo root takes precedence over dashboard build settings. If your build command or publish directory is not behaving as expected, check the repo root for this file. Either update it or remove it if you want the dashboard to be the source of truth. Deploy Previews not generating for pull requests. Go to Site Settings > Build and Deploy > Deploy Previews and confirm they are enabled. Also check that the Netlify GitHub App has access to the repo, not just the OAuth connection, as PR webhook events sometimes do not fire correctly through OAuth. For teams hitting build errors repeatedly, why software deployments fail and how to fix them covers the underlying patterns that cause most deploy failures regardless of platform._** If your project has a backend, a database, WebSockets, or you have simply hit Netlify’s 300-minute build cap, the problem is not your workflow. The problem is that Netlify was built for static sites and the GitHub integration reflects that constraint. What you need is a GitHub integration that deploys your entire stack, not just the files your build command produces. Kuberns is an Agentic AI cloud platform built for exactly this. It connects to GitHub the same way Netlify does: authorize the app, select your repo and branch. What happens after that is fundamentally different. Step 1: Connect your GitHub repo. Kuberns installs on your GitHub account in one click. Select the repo and the branch you want as production. Kuberns reads the codebase, detects your stack automatically (Node.js, Python, Go, PHP, Docker, full-stack monorepo), and configures the build pipeline without any Dockerfiles or service definitions. Step 2: Set your environment variables. Add your secrets and config in the Kuberns dashboard. Variables are injected at runtime on the server, not baked into a static build. Your backend, database connection strings, and API keys are all handled correctly without workarounds. Step 3: Click Deploy. Kuberns builds your frontend, starts your backend as a persistent process on AWS, provisions your database, configures SSL, and gives you a live HTTPS URL. Frontend and backend go live together in a single deploy. No separate hosting accounts. No Functions workarounds. No cold starts. What every push to GitHub triggers on Kuberns: This is not a static file swap on a CDN. It is a full zero downtime rolling deployment of your entire application stack, automated on every push. What Kuberns handles that Netlify does not: For teams hitting Netlify’s GitHub integration limits, the switch to Kuberns does not require rewriting your workflow. You push to GitHub, the deployment happens. The difference is what gets deployed and how far it goes. For frontend-only static sites, Netlify’s GitHub integration is fast and frictionless. For anything with a backend, the image above explains why teams move. See the best tools to deploy backend apps in 2026 for a broader comparison of what each platform actually supports. Already using auto-deploy from GitHub on Kuberns? That guide walks through the full one-click GitHub setup on the Kuberns platform.

_** Netlify’s GitHub integration is genuinely well-built for what it is designed to do: deploy static sites and frontend builds automatically on every push. The setup takes minutes, Deploy Previews are useful, and for frontend-only projects it rarely breaks. The limits are structural, not fixable. If your project has a backend, a database, or any requirement that goes beyond serving static files, Netlify’s GitHub integration will push you toward workarounds that do not fully solve the problem. Kuberns gives you the same simple GitHub connect workflow with full-stack deployment on the other side of it. Connect your GitHub repo and deploy your full stack on Kuberns Templates let you quickly answer FAQs or store snippets for re-use. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse