Netlify GitHub 연동: 설정, 제한 사항 및 해결 방법

Netlify의 GitHub 연동은 여러분의 저장소(repo)를 연결하여 매 푸시(push)마다 몇 분 안에 자동으로 배포(auto-deploy)합니다. 정적 사이트(static sites) 및 프론트엔드 전용 프로젝트의 경우, 광고된 대로 정확하게 작동합니다. 하지만 풀스택 앱(full-stack apps)의 경우, 이 연동 방식은 빠르게 한계에 부딪히며, 이러한 한계는 이미 프로덕션(production) 환경에 진입하기 전까지는 항상 명확하게 드러나지 않습니다.

이 가이드는 Netlify GitHub 연동이 실제로 어떻게 작동하는지, 단계별 연결 방법, 연동이 실패하는 구체적인 지점, 가장 흔한 오류와 그 해결 방법, 그리고 Netlify GitHub 연동이 프로젝트에 충분하지 않을 때 무엇을 사용해야 하는지를 다룹니다.

Netlify GitHub 연동이란 무엇이며 어떻게 작동하는가?

Netlify GitHub 연동이란 무엇이며 어떻게 작동하는가

Netlify GitHub 연동은 GitHub 저장소를 Netlify 사이트에 연결하는 지속적 배포 파이프라인(continuous deployment pipeline)입니다. 설정된 브랜치(branch)에 푸시하면, Netlify는 저장소를 클론(clone)하고, 빌드 명령(build command)을 실행하며, 정적 출력물(static output)을 자체 CDN에 게시합니다. 수동 업로드, FTP, 대시보드에서의 배포 재실행이 필요 없습니다.

Netlify가 GitHub에 연결하는 방식에는 두 가지가 있습니다:

**OAuth2 인증 (OAuth2 authentication)**은 개인 액세스 토큰(personal access token)을 사용하여 Netlify에 저장소 접근 권한을 부여합니다. 이는 기본 방식이며 설정이 가장 빠릅니다. 단점은 GitHub 토큰을 교체하거나 계정 권한을 변경할 경우, 연결이 조용히 끊어진다는 점입니다.

Netlify GitHub App은 개인 토큰 대신 설치 수준의 범위 지정된 권한(scoped permissions)을 사용합니다. 이는 더 안전하고, 더 세밀하며, 개인 토큰이 변경되어도 연결이 끊기지 않습니다. 어떤 팀 환경에서든 이 방식이 사용할 가치가 있는 연결 방법입니다.

연결이 완료되면, Netlify는 GitHub 웹훅 (webhook)을 통해 푸시 이벤트 (push events)를 감지합니다. 프로덕션 브랜치 (production branch)에 대한 모든 푸시는 새로운 빌드 (build)를 트리거합니다. 모든 풀 리퀘스트 (pull request)는 배포 미리보기 (Deploy Preview)를 생성합니다. 이는 branch-name--your-site.netlify.app 형태의 고유한 라이브 URL로, 머지 (merge)하기 전에 변경 사항을 검토할 수 있는 환경을 제공합니다. 브랜치 배포 (Branch deploys)를 사용하면 스테이징 (staging) 또는 기능 브랜치 (feature branches)를 위해 별도의 빌드를 실행할 수 있습니다.

가장 핵심적으로 이해해야 할 점은 Netlify가 실제로 무엇을 배포하느냐 하는 것입니다. 바로 빌드 명령의 정적 출력물 (static output)입니다. Netlify는 서버를 실행하지 않습니다. 파일을 게시할 뿐입니다. 이러한 차이점이 프론트엔드 (frontend) 프로젝트에서는 통합이 원활하게 작동하도록 만드는 반면, 지속적인 백엔드 프로세스 (backend process)가 필요한 모든 경우에는 강력한 차단 요소 (hard blockers)가 됩니다.

****

Netlify 호스팅이 정확히 무엇을 다루고 어디까지 지원하는지 이해하려면, 해당 가이드에서 플랫폼의 실제 배포 모델을 자세히 설명하고 있습니다.
**

GitHub를 Netlify에 연결하는 단계별 방법

1단계: Git에서 새 사이트 생성하기. Netlify 대시보드에서 Add new site를 클릭한 다음, Import an existing project를 선택합니다. Git 제공업체로 GitHub를 선택합니다.

2단계: Netlify 권한 부여하기. GitHub에서 Netlify GitHub App 또는 OAuth 연결을 승인하라는 메시지가 표시됩니다. 팀 리포지토리 (team repos)의 경우, 모든 리포지토리에 대한 액세스 권한을 부여하는 대신 GitHub App을 선택하여 특정 조직 (organization) 또는 리포지토리에 설치하십시오.

3단계: 리포지토리 및 브랜치 선택하기. 사용할 리포지토리와 프로덕션 브랜치로 사용할 브랜치를 선택합니다. 이것이 Netlify가 푸시를 감시할 브랜치입니다. 일반적으로 main 또는 master입니다.

4단계: 빌드 설정 구성하기. 대부분의 경우 Netlify가 프레임워크 (frameworks)를 자동으로 감지합니다. 감지되지 않을 경우, 프레임워크별 올바른 설정은 다음과 같습니다:

5단계: 환경 변수 (environment variables) 추가. 고급 빌드 설정 (Advanced build settings) 아래에 빌드에 필요한 모든 환경 변수를 추가합니다. 여기에 추가된 변수들은 빌드 프로세스 중에 사용할 수 있습니다. 이를 Netlify Functions를 위한 런타임 환경 변수 (runtime environment variables)와 혼동하지 마세요. 런타임 환경 변수는 별도로 구성됩니다.

6단계: 배포 (Deploy). 'Deploy site'를 클릭합니다. 첫 번째 배포는 2~5분이 소요됩니다. 이후의 배포는 Netlify가 의존성 (dependencies)을 캐싱하기 때문에 더 빠릅니다. 이 시점부터는 프로덕션 브랜치 (production branch)에 푸시(push)할 때마다 자동으로 새로운 배포가 트리거됩니다.

고급 설정을 위해서는 리포지토리 (repo)의 루트에 netlify.toml 파일을 추가하세요:

[build]
  command = "npm run build"
  publish = "dist"
...

참고: netlify.toml의 설정은 대시보드 설정을 별도의 알림 없이 덮어씁니다 (override). 만약 대시보드 설정이 적용되지 않는다면, 리포지토리에 있는 netlify.toml 파일이 이를 덮어쓰고 있을 가능성이 높습니다.

**

첫 번째 배포 이후 커스텀 도메인 (custom domains)을 연결하는 팀의 경우, DNS 설정 오류 없이 배포된 앱에 커스텀 도메인을 추가하는 방법을 참조하세요.
**

Netlify GitHub 연동은 어디서 문제가 발생하는가?

설정 자체는 잘 작동합니다. 문제는 프로젝트가 단순한 프론트엔드 빌드 (frontend build) 수준을 넘어 성장하여, 주로 프로덕션 (production) 환경에 도달했을 때 나타납니다.

Netlify는 정적 출력물 (Static Output)만 배포합니다

Netlify는 빌드 명령을 실행하고 그 결과물을 게시합니다. Netlify는 서버 프로세스 (server process)를 실행하지 않습니다. 만약 앱에 Node.js, Python, Go 또는 기타 백엔드 (backend)가 있다면, Netlify는 이를 배포하지 않습니다. 이것은 설정의 문제가 아닙니다. Netlify가 작동하는 방식의 근본적인 제약 사항 (fundamental constraint)입니다.

Netlify Functions는 간단한 서버리스 로직 (serverless logic)을 위한 해결책을 제공하지만, 다음과 같은 엄격한 제한 사항 (hard limits)이 따릅니다: 무료 티어 (free tier)에서는 10초의 실행 시간 제한 (execution timeout)이 적용되며, Pro 티어에서는 26초가 적용됩니다. WebSockets를 사용할 수 없습니다. 지속적인 연결 (persistent connections)도 불가능합니다. 백그라운드 작업 (background jobs)도 지원하지 않습니다. 데이터베이스 연결을 처리하거나, 데이터를 스트리밍하거나, 긴 작업 (long operations)을 실행해야 하는 모든 API의 경우, Netlify Functions는 실제 백엔드 (backend)의 대체재가 될 수 없습니다. 완전한 분석 내용은 Netlify에 실제로 백엔드를 배포할 수 있는지 여부를 참조하십시오.

무료 티어에서 빌드 시간 제한 (Build Minute Caps)에 빠르게 도달함

Netlify의 무료 티어에는 월 300분의 빌드 시간 (build minutes)이 포함되어 있습니다. 일반적인 React 또는 Next.js 빌드는 24분이 소요됩니다. 이는 제한에 도달하기 전까지 한 달에 대략 75150회의 배포 (deploys)가 가능하다는 것을 의미합니다. 모든 PR (Pull Request)과 main 브랜치로의 모든 푸시 (push)마다 배포를 진행하는 팀의 경우, 무료 티어는 첫 주 만에 소진됩니다.

풀스택 프레임워크 (Full-Stack Frameworks)는 특정 플러그인 필요

Next.js App Router, Nuxt 3, SvelteKit은 정적 출력 (static-output) 프레임워크가 아닙니다. 이들은 서버 사이드 렌더링 (server-side rendering), API 라우트 (API routes), 그리고 엣지 함수 (edge functions)를 필요로 합니다. Netlify는 어댑터 플러그인 (adapter plugins)을 통해 이를 지원하지만, 모든 기능이 커버되는 것은 아닙니다. Netlify에서의 Next.js App Router 지원은 부분적이며, 증분 정적 재생성 (Incremental Static Regeneration)이나 특정 미들웨어 (middleware) 동작과 같은 일부 기능은 해결책 (workarounds)이 필요하거나 단순히 작동하지 않을 수 있습니다. Netlify에 Next.js를 배포하는 전체적인 모습에서는 어떤 기능이 지원되고 어떤 기능이 지원되지 않는지를 정확히 다룹니다.

리포지토리 권한 변경 시 OAuth 토큰 오류 발생

OAuth 연결 방식을 사용하다가 나중에 GitHub에서 리포지토리 액세스 권한을 변경하는 경우 (리포지토리 이전, 조직 권한 변경 또는 토큰 교체 등), Netlify는 조용히 액세스 권한을 잃게 됩니다. 사이트 대시보드에는 다음 푸시가 배포를 트리거하는 데 실패할 때까지 아무런 오류도 표시되지 않습니다. Netlify GitHub App으로 전환하면 이러한 문제를 피할 수 있는데, 이는 권한이 개인 토큰 (personal token)이 아닌 설치 (installation) 범위로 지정되기 때문입니다.

빌드 타임 (Build-Time) vs 런타임 (Runtime) 환경 변수의 동작 차이

Netlify의 빌드 설정(build settings)에 추가된 변수들은 빌드 타임 (Build-Time)에 주입되어 정적 출력물(static output)에 포함됩니다. 이 변수들은 Netlify Functions의 환경 설정(environment configuration)에 명시적으로 추가되지 않는 한, 런타임 (Runtime)에는 사용할 수 없습니다. 이로 인해 대시보드에 추가한 API 키가 서버리스 함수(serverless function) 로그에서 확인되지 않아 팀들이 당황하는 경우가 발생합니다.

*_

Netlify의 요금제 (pricing tier)에 따라 빌드 시간 허용량, 함수 실행 제한 및 팀 시트(team seat) 비용이 결정됩니다. 규모를 확장하기 전에 검토해 볼 가치가 있습니다.
_**

가장 흔한 Netlify GitHub 연동 오류 해결 방법

푸시(push) 후 배포(Deploy)가 트리거되지 않는 경우. 푸시한 브랜치가 Site Settings > Build and Deploy > Continuous Deployment의 프로덕션 브랜치와 일치하는지 확인하세요. 그다음 GitHub 리포지토리(repo)의 Settings > Webhooks로 이동하여 최근 전송(deliveries) 항목에 Netlify 웹훅(webhook)이 녹색 체크 표시로 나타나는지 확인하십시오. 웹훅이 실패하고 있다면, 이를 삭제하고 Netlify에서 리포지토리를 다시 연결하세요.

연결 직후 빌드가 실패하는 경우. 가장 흔한 원인은 락파일(lockfile, package-lock.json 또는 yarn.lock) 누락(커밋되지 않음), Node 버전 불일치, 또는 잘못된 게시 디렉토리(publish directory)입니다. 배포 로그(deploy log)에서 정확한 에러 라인을 확인하세요. Site Settings에서 올바른 Node 버전을 설정하거나, netlify.toml 파일의 NODE_VERSION을 통해 설정하십시오.

프라이빗 리포지토리(Private repo)가 찾을 수 없음으로 표시되는 경우. OAuth 토큰이 해당 리포지토리에 대한 액세스 권한을 가지고 있지 않습니다. GitHub Settings > Applications > Authorized OAuth Apps로 이동하여 Netlify의 액세스 권한을 취소한 다음, Netlify 사이트 설정에서 다시 연결하십시오. 더 나은 장기적 해결책은 설치 범위 권한(installation-scoped permissions)을 사용하는 Netlify GitHub App으로 전환하는 것입니다.

netlify.toml이 대시보드 설정을 덮어쓰는 경우. 저장소 루트(repo root)에 있는 netlify.toml 파일은 대시보드 빌드 설정보다 우선순위를 가집니다. 빌드 명령(build command)이나 게시 디렉토리(publish directory)가 예상대로 작동하지 않는다면, 저장소 루트에 이 파일이 있는지 확인하세요. 대시보드를 신뢰할 수 있는 단일 소스(source of truth)로 사용하고 싶다면 이 파일을 업데이트하거나 삭제해야 합니다.

Pull Request(PR)에 대해 Deploy Previews가 생성되지 않는 경우. Site Settings > Build and Deploy > Deploy Previews로 이동하여 해당 기능이 활성화되어 있는지 확인하세요. 또한, OAuth 연결뿐만 아니라 Netlify GitHub App이 해당 저장소에 대한 접근 권한을 가지고 있는지 확인해야 합니다. OAuth를 통해서는 PR 웹훅(webhook) 이벤트가 가끔 올바르게 발생하지 않을 수 있기 때문입니다.

**———

빌드 오류가 반복적으로 발생하는 팀을 위해, 왜 소프트웨어 배포가 실패하고 이를 어떻게 해결하는가에서는 플랫폼과 관계없이 대부분의 배포 실패를 유발하는 근본적인 패턴을 다룹니다.
———

Netlify GitHub 연동만으로 충분하지 않을 때, Kuberns를 사용하세요

프로젝트에 백엔드(backend), 데이터베이스(database), 웹소켓(WebSockets)이 있거나 단순히 Netlify의 300분 빌드 제한(build cap)에 도달했다면, 문제는 워크플로(workflow)에 있는 것이 아닙니다. 문제는 Netlify가 정적 사이트(static sites)를 위해 구축되었으며, GitHub 연동 또한 그러한 제약을 반영하고 있다는 점입니다. 여러분에게 필요한 것은 단순히 빌드 명령이 생성하는 파일뿐만 아니라, 전체 스택(entire stack)을 배포할 수 있는 GitHub 연동입니다.