30초 요약
- 저장소 Settings → Pages → Build and deployment의 Source를 GitHub Actions로 바꾼다.
.github/workflows/deploy.yml에 Astro 공식 문서의 워크플로(withastro/action+actions/deploy-pages)를 둔다.astro.config.mjs에site와base를 설정한다.<username>.github.io저장소가 아니면base에 저장소 이름이 필요하다.main에 push하면 빌드와 배포가 돈다. 수동 실행(workflow_dispatch)도 된다.
목표
Astro 프로젝트를 GitHub 저장소에 올리고, push할 때마다 GitHub Actions가 빌드해서 GitHub Pages에 배포하게 만든다. 빌드 결과(dist)를 저장소에 커밋하지 않는다.
원인: 왜 Actions 배포인가
GitHub Pages는 저장소의 정적 파일을 서비스한다(무료 플랜은 공개 저장소만). 공식 문서에 따르면 게시 소스를 GitHub Actions로 고르면, 워크플로가 파일을 빌드해 올리고(actions/upload-pages-artifact) 배포(actions/deploy-pages)하는 방식으로 쓴다. Astro는 이 두 단계를 묶은 공식 액션 withastro/action을 제공한다.
액션은 lock 파일을 보고 패키지 관리자(npm, yarn, pnpm, bun)를 감지한다. 따라서 해당 lock 파일(package-lock.json 등)을 저장소에 커밋해 두어야 한다.
해결 방법
1. Pages 소스를 GitHub Actions로 바꾼다
저장소의 Settings에서 사이드바의 Pages를 열고, Build and deployment의 Source를 GitHub Actions로 고른다(GitHub 문서, Astro 문서 모두 같은 안내).
2. site와 base를 설정한다
Astro 문서는 site를 배포된 사이트의 GitHub URL로, base를 저장소를 가리키는 값(예: /my-repo)으로 두라고 안내한다. <username>.github.io 저장소는 base를 생략한다.
import { defineConfig } from 'astro/config';
export default defineConfig({ site: 'https://username.github.io', base: '/myrepo',});이 설정이 빠졌을 때 CSS·JS가 404가 나는 문제는 GitHub Pages에 배포한 Astro 사이트 CSS·JS 404 오류 해결에서 다룬다. 이 글에서는 반복하지 않는다.
3. 워크플로 파일을 만든다
.github/workflows/deploy.yml을 만든다. 아래는 Astro 공식 문서의 예시다.
name: Deploy to GitHub Pageson: push: branches: [ main ] workflow_dispatch:
permissions: contents: read pages: write id-token: write
jobs: build: runs-on: ubuntu-latest steps: - name: Checkout your repository using git uses: actions/checkout@v7 - name: Install, build, and upload your site uses: withastro/action@v6
deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v5withastro/action의 입력은 모두 선택이다(README 기준).
| 입력 | 뜻 | 기본값 |
|---|---|---|
path | Astro 프로젝트의 루트 위치 | 저장소 루트 |
node-version | Node 버전 | 24 |
package-manager | npm, yarn, pnpm, bun, deno | lock 파일로 자동 감지 |
build-cmd | 빌드 명령 | 패키지 관리자의 build 스크립트 |
cache | 빌드 캐시 사용 | true |
cache-dir | 캐시 디렉터리 | node_modules/.astro |
out-dir | 출력 디렉터리 | dist |
프로젝트가 하위 폴더에 있으면 with: path: ./web처럼 지정한다. 액션 버전 태그(@v6, @v7, @v5)는 문서 작성 시점의 값이므로 사용할 때 공식 문서에서 다시 확인한다.
4. 커밋하고 push한다
main에 push하면 Actions 탭에서 build와 deploy 잡이 차례로 돈다. 배포가 끝나면 deploy 잡의 environment URL(page_url)에 사이트 주소가 나온다. Actions 탭에서 수동으로 돌리고 싶으면 workflow_dispatch 덕분에 Run workflow 버튼을 쓸 수 있다.
5. 커스텀 도메인을 쓴다면
Astro 문서의 순서는 다음과 같다.
- 도메인 제공업체에서 DNS를 설정한다.
./public/CNAME파일에 도메인(예:sub.example.com)을 적는다.- Astro 설정에서
site를https://example.com형태로 바꾸고base를 지운다. - 내부 링크에서
base접두어를 제거한다.
확인
러너 안에서 빈 Astro 프로젝트를 만들어 세 가지를 확인했다. 첫째, 위 워크플로 파일에 pages: write·id-token: write 권한과 두 액션이 들어 있다. 둘째, site·base를 설정하고 npm run build를 한 결과의 CSS 링크가 /myrepo/ 아래로 만들어지고, public/CNAME이 dist 루트로 복사된다. 셋째, base: '/myrepo'이면 import.meta.env.BASE_URL도 끝 슬래시 없는 /myrepo라서, 내부 링크는 사이에 슬래시를 넣어 붙여야 /myrepo/about/가 된다. GitHub Pages 프로젝트 경로를 흉내 낸 로컬 서버(/myrepo)에서 요청한 결과는 아래 로그와 같다. 설정이 없는 빌드는 [BEFORE], 설정한 빌드는 [AFTER] 구간이다.
검증 범위: 워크플로 파일의 권한·액션 항목,
site·base설정에 따른 빌드 결과와 로컬 서버 응답은 실행으로 확인했다. Pages 소스 설정, Actions 실행과deploy-pages배포, 커스텀 도메인 DNS는 공식 문서로 대조했다. 작은 CSS는 기본 설정에서 HTML에 인라인되어 링크가 사라지므로, 검증 프로젝트는build.inlineStylesheets: 'never'로 두었다.
검증 환경 5항목
| OS | Ubuntu 24.04.5 |
|---|---|
| Astro | 7.3.5 |
| Node | 22.23.3 |
| 실행 날짜 | 2026-10-05 |
| 작성자 기재 환경 | GitHub 호스티드 ubuntu-latest 러너 (빌드와 로컬 서버 확인. Actions 배포 자체는 문서 대조) |
[PASS] 워크플로에 pages: write 권한이 있다 [PASS] 워크플로에 id-token: write 권한이 있다 [PASS] 워크플로가 withastro/action과 actions/deploy-pages를 쓴다
[PASS] base 없이 빌드가 끝났다
[PASS] 빌드 결과에서 CSS 링크를 찾았다 (base 없음)
[PASS] base 없을 때 CSS 링크는 /_astro/로 시작한다
서버 시작: 127.0.0.1:8081 (python3 -m http.server 8081 --bind 127.0.0.1 --directory '/tmp/tmp.GvAoo14DXY/serve-before')
[XFAIL] 프로젝트 경로를 흉내 낸 로컬 서버(/myrepo)에서 base 없는 빌드의 /_astro/index.CgMySlMw.css 요청 — 예상된 실패 재현됨 (/HTTP 404 GET http://127.0.0.1:8081/_astro/index.CgMySlMw.css/)
> HTTP 404 GET http://127.0.0.1:8081/_astro/index.CgMySlMw.css[PASS] site·base 설정 뒤 빌드가 끝났다
[PASS] 빌드 결과에서 CSS 링크를 찾았다 (base 있음)
[PASS] CSS 링크가 /myrepo/_astro/로 시작한다
[PASS] base가 '/myrepo'면 BASE_URL도 끝 슬래시 없이 /myrepo다
[PASS] BASE_URL에 about/을 바로 붙이면 /myrepoabout/ 가 된다
[PASS] 끝 슬래시를 맞춰 붙인 내부 링크가 /myrepo/about/ 가 된다
[PASS] public/CNAME이 dist 루트로 복사된다
서버 시작: 127.0.0.1:8082 (python3 -m http.server 8082 --bind 127.0.0.1 --directory '/tmp/tmp.GvAoo14DXY/serve-after')
[PASS] 프로젝트 경로를 흉내 낸 로컬 서버(/myrepo)에서 /myrepo/_astro/index.CgMySlMw.css 요청
> HTTP 200 GET http://127.0.0.1:8082/myrepo/_astro/index.CgMySlMw.css
[PASS] 프로젝트 경로를 흉내 낸 로컬 서버(/myrepo)에서 /myrepo/about/ 요청
> HTTP 200 GET http://127.0.0.1:8082/myrepo/about/주의
actions/deploy-pages문서는 배포 잡에 최소한pages: write와id-token: write권한이 있어야 한다고 적는다.pages: write는 Pages 배포를 만드는 데,id-token: write는 배포가 적절한 출처에서 왔는지 확인하는 OIDC 토큰을 받는 데 쓴다. 공식 예시의permissions를 그대로 둔다.base를/myrepo처럼 끝 슬래시 없이 두면import.meta.env.BASE_URL도/myrepo다. 내부 링크를${import.meta.env.BASE_URL}about/처럼 바로 붙이면/myrepoabout/가 된다. 사이에 슬래시가 하나 들어가게 붙인다.- lock 파일을 커밋하지 않으면 액션이 패키지 관리자를 감지하지 못한다.
- GitHub 문서는 deployment protection rules로 배포를 기본 브랜치에만 허용하길 권장한다.
- 커스텀 도메인으로 바꾸면
base를 지우고 내부 링크의base접두어도 정리한다.
자주 묻는 질문
빌드 결과(dist)를 저장소에 커밋해야 하나?
아니다. 워크플로가 withastro/action으로 빌드한 결과를 아티팩트로 올리고 actions/deploy-pages가 배포한다. 저장소에는 소스와 lock 파일만 둔다.
pnpm이나 yarn을 써도 되나?
된다. 액션이 lock 파일로 패키지 관리자를 자동 감지하며, package-manager 입력으로 지정할 수도 있다. 해당 lock 파일은 커밋해야 한다.
Astro 프로젝트가 저장소 하위 폴더에 있다면?
withastro/action의 path 입력에 프로젝트 루트 위치를 준다.
<username>.github.io 저장소도 base가 필요한가?
필요 없다. Astro 문서는 이 형태의 저장소에서만 base 설정을 생략할 수 있다고 안내한다.