출처 대조 B · GitHub 호스티드 ubuntu-latest 러너

검증 환경: GitHub 호스티드 ubuntu-latest 러너 (빌드와 로컬 서버 확인. Actions 배포 자체는 문서 대조)

게시 2026-10-05최종 확인 2026-10-05읽기 6분

Astro를 GitHub Actions로 GitHub Pages에 배포하기

withastro/action과 actions/deploy-pages로 Astro 사이트를 GitHub Pages에 배포하는 워크플로 작성법. Pages 소스 설정, site·base, 커스텀 도메인 CNAME까지 정리한다.

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 등)을 저장소에 커밋해 두어야 한다.

main에 push하면 build 잡이 withastro/action으로 빌드하고, deploy 잡이 actions/deploy-pages로 GitHub Pages에 배포한다main에 pushbuild 잡withastro/action@v6deploy 잡actions/deploy-pages@v5GitHub Pages 공개
push부터 배포까지의 흐름 (보라 = 사람 · 파랑 = 자동 · 초록 = 외부)

해결 방법

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를 생략한다.

astro.config.mjs
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 Pages
on:
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@v5

withastro/action의 입력은 모두 선택이다(README 기준).

입력뜻기본값
pathAstro 프로젝트의 루트 위치저장소 루트
node-versionNode 버전24
package-managernpm, yarn, pnpm, bun, denolock 파일로 자동 감지
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 문서의 순서는 다음과 같다.

  1. 도메인 제공업체에서 DNS를 설정한다.
  2. ./public/CNAME 파일에 도메인(예: sub.example.com)을 적는다.
  3. Astro 설정에서 site를 https://example.com 형태로 바꾸고 base를 지운다.
  4. 내부 링크에서 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'로 두었다.

CI 실행 결과 · 수정 전 재현 1건 · 수정 후 15/15 단계 성공
검증 환경 5항목
OSUbuntu 24.04.5
Astro7.3.5
Node22.23.3
실행 날짜2026-10-05
작성자 기재 환경GitHub 호스티드 ubuntu-latest 러너 (빌드와 로컬 서버 확인. Actions 배포 자체는 문서 대조)
실행 기록
[PASS] 워크플로에 pages: write 권한이 있다
[PASS] 워크플로에 id-token: write 권한이 있다
[PASS] 워크플로가 withastro/action과 actions/deploy-pages를 쓴다
수정 전 재현 · 예상된 실패 1건 재현됨수정 전: site·base 없이 빌드한다
[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
수정 후 확인 · 9/9 단계 성공수정 후: site와 base를 설정하고 다시 빌드한다
[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/
이 결과는 글의 명령어를 GitHub Actions의 깨끗한 환경에서 그대로 실행해 자동으로 붙인 것입니다.

주의

  • 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 설정을 생략할 수 있다고 안내한다.

참고 자료