software

Angular 웹사이트를 GitHub Pages에 배포하는 방법

발행: (2026년 1월 15일 오전 01:43 GMT+9)
8 min read
원문: Dev.to

Source: Dev.to

I’m ready to translate the article for you, but I’ll need the full text you’d like translated. Could you please paste the content (excluding code blocks and URLs) here? Once I have it, I’ll provide the Korean translation while preserving the original formatting.

Angular와 GitHub Pages

다행히 Angular 웹 애플리케이션을 GitHub Pages에 배포하기 위한 다소 “공식적인” 방법이 존재합니다. 서드파티 스크립트이지만 angular-cli-ghpages (GitHub repo)는 공식적으로 가장 좋고 권장되는 방법으로 받아들여지고 있습니다. 저는 바로 적용해 보았고 바로 동작했기에 사용했습니다.

저는 일반적으로 외부 라이브러리에 의존하지 않기 위해 내장 솔루션을 선호하지만, 이번 경우에 한해 예외를 두었습니다. 이는 나중에 Flutter로 전환할 계획이 있기 때문이며, 해당 스크립트가 제가 필요로 하는 모든 기능(맞춤 도메인 지원 포함)을 이미 제공하기 때문입니다.

저는 게시 전략을 GitHub‑Actions만 사용하는 흐름에서 gh-pages 브랜치를 사용하는 방식으로 바꿔야 했지만, 여전히 GitHub Actions를 함께 사용하고 있습니다. 혼란을 피하기 위해 같은 브랜치에 모두 유지하는 것이 이상적이었지만, 현재로서는 gh-pages 브랜치가 잘 작동하고 있습니다.

무엇, 무엇이 아닌가, 그리고 뭐야

  1. 저도 업무에서 사용합니다.
  2. WebAssembly를 통해 Rust와 결합된 흥미로운 프로젝트들을 발견했습니다.
  3. Antigravity와 쉽게 통합됩니다.

Angular가 “최고” 프레임워크라서가 아니라; 저는 여전히 프레임워크는 특정 요구에 따라 선택되어야 한다고 믿습니다.

현재 수요를 기준으로 프레임워크를 선택해야 한다면 React + Next.js를 선택할 것이고, 그것을 사용할 방법도 찾을 수 있을 겁니다. 개인 포트폴리오라면 현대적인 프레임워크라면 어느 것이든 괜찮습니다.

수년간 프레임워크 없이 사이트를 만들었습니다. 제가 개인 웹사이트에 가장 오래 사용한 구조는 WordPress였습니다. 여전히 존재하지만, 이 용도로 아직도 사용하는 사람이 있을까요? 솔직히, 그렇지 않길 바랍니다— 제품이 나쁘기 때문이 아니라, 그때가 이미 지나갔기 때문입니다. 비록 PHP가 약간 부활하고 있긴 하지만.

Angular을 GitHub Pages에 배포하기

배포 단계를 추가하는 방법은 두 가지가 있습니다:

  • 수동으로 angular-cli-ghpages 패키지를 설치합니다.
  • Angular CLI를 이용하는 방법으로, 이 경우 angular.json에 deploy 항목이 자동으로 추가됩니다.

저는 후자를 선택했습니다. 다음 명령을 실행합니다:

ng add angular-cli-ghpages

전제: Angular CLI가 전역에 설치되어 있어야 합니다.

다음으로 게시 설정을 업데이트합니다(기본 GitHub‑Pages 소스를 gh-pages 브랜치로 교체). angular.json에 아래와 같은 deploy 구성을 추가합니다:

{
  "deploy": {
    "builder": "angular-cli-ghpages:deploy",
    "options": {
      "name": "John Doe",
      "email": "john.doe@foo.bar",
      "cname": "foo.bar"
    }
  }
}

name, email, cname을 자신의 GitHub 자격 증명 및 커스텀 도메인으로 교체하세요(cname 키는 커스텀 도메인을 사용할 때만 필요합니다).

ng deploy를 실행하면 이제 빌드된 사이트가 gh-pages 브랜치에 푸시됩니다(브랜치가 없으면 자동으로 생성됩니다). 이제 이를 GitHub Actions로 자동화해 보겠습니다.

Source:

Automatic Deployment with GitHub Actions

특별한 요구 사항이 없으면, 클래식 개인 액세스 토큰(PAT)을 Developer Settings에서 repo와 user 범위를 모두 선택하여 생성하는 것만 추가로 하면 됩니다. 이 토큰을 저장소의 시크릿에 GH_TOKEN으로 저장하세요.

워크플로 파일(예: .github/workflows/deploy.yml)을 다음 내용으로 만들세요:

name: Deploy to GitHub Pages

on:
  push:
    branches: ['main']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24.x'

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Deploy
        run: npm run deploy
        env:
          CI: true
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
  • GitHub Actions에 이미 익숙하다면 이 과정은 간단할 것입니다.
  • 마지막 세 명령(npm install, npm run build, npm run deploy)은 angular-cli-ghpages가 Angular 설정을 자동으로 감지하므로 한 줄로 합칠 수 있습니다—단, 최신 버전의 프레임워크를 사용해 문제를 방지하세요.

주의할 점

  • 토큰 생성 – 개인 설정 페이지에서 새 PAT를 만들고 이를 저장소의 비밀(GH_TOKEN)로 저장합니다. 비밀 이름은 원하는 대로 지정할 수 있으며, 그에 맞게 secrets.GH_TOKEN 참조를 조정하면 됩니다.
  • 워크플로 파일 위치 – 파일은 저장소 루트에 있는 .github/workflows 폴더에 배치하고, 확장자는 .yml(또는 .yaml)이어야 합니다. 내 파일은 deploy.yml이라고 했지만, 이름은 중요하지 않습니다.
  • gh-pages 브랜치 – 별도의 gh-pages 브랜치를 유지하는 것은 선호하지 않지만, 현재 서드파티 패키지가 이를 요구하므로 당분간은 유지합니다. 곧 더 깔끔한 해결책을 찾을 수 있기를 바랍니다.

이제 끝! Angular 사이트가 main에 푸시될 때마다 자동으로 빌드되어 GitHub Pages에 배포됩니다.

제대로 동작하고, 그게 전부였습니다.

원하신다면 Bluesky와/또는 GitHub에서 저를 팔로우해 주세요. 저는 네트워킹을 즐깁니다.

Back to Blog

관련 글

더 보기 »