Angular 19을 GitHub Pages에 GitHub Actions로 배포하는 방법
카테고리
프로그래밍/소프트웨어 개발
서브카테고리
DevOps
대상자
Angular 19 프로젝트를 GitHub Pages에 자동 배포하는 개발자, GitHub Actions를 사용한 CI/CD 경험자
핵심 요약
- GitHub Actions 워크플로우는
actions/upload-pages-artifact@v3
와actions/deploy-pages@v4
의 호환성 문제를 해결해야 함 angular.json
의baseHref
와outputPath
설정이 프로젝트 이름과 리포지토리 이름을 일치시켜야 404 오류를 방지- Angular 17+ 부터
dist/[프로젝트명]/browser
폴더가 빌드 결과물의 기본 경로로 변경됨
섹션별 세부 요약
1. 워크플로우 템플릿
actions/upload-pages-artifact@v3
와actions/deploy-pages@v4
를 사용해 빌드 및 배포 프로세스 구현npm ci
,npx ng build
명령어로 빌드 수행 후.nojekyll
파일 생성dist/[프로젝트명]/browser
폴더를 GitHub Pages에 업로드
2. 첫 번째 문제: `Missing download info`
actions/upload-pages-artifact@v2
대신v3
을 사용해도 호환성 문제 발생deploy-pages@v4
는upload-pages-artifact@v2
의 아티팩트 형식을 기대함- 문서화가 뒤처진 예제 참고 시 버전 불일치 문제 발생
3. 커스텀 도메인 문제
- GitHub Pages 기본 도메인(
[유저명].github.io
) 대신altaskur.live
와 같은 커스텀 도메인 사용 시 - 프로젝트 경로(
[리포지토리명]
)와baseHref
설정 미일치로 404 오류 발생
4. 프로젝트 경로 문제
angular.json
에서outputPath
과baseHref
값을 리포지토리 이름으로 설정해도 404 오류 지속dist/[프로젝트명]/browser
폴더가 실제 빌드 결과물 경로임을 확인browser
폴더를 대상으로 설정해index.html
파일이 존재하는지 확인
5. 배포 내용 문제
ls -lah dist/[프로젝트명]/browser
명령어로browser
폴더 내 파일 존재 여부 확인index.html
파일이browser
폴더에 위치해 있어dist/[프로젝트명]
폴더만 지정하면 404 발생
6. 결론
- Angular 17+ 부터 빌드 결과물 경로가
browser
폴더로 변경됨 angular.json
의outputPath
과baseHref
설정, GitHub Actions 워크플로우의dist/[프로젝트명]/browser
경로를 정확히 일치시켜야 함
결론
- Angular 19의 GitHub Pages 자동 배포는
browser
폴더 경로 설정,baseHref
및outputPath
일치,actions/upload-pages-artifact@v3
와deploy-pages@v4
호환성 문제 해결이 핵심 dist/[프로젝트명]/browser
폴더 내index.html
파일 존재 여부를ls
명령어로 확인해 빌드 결과물 위치를 정확히 파악해야 함