배포·자동화 매뉴얼

GitHub Pages로 정적 사이트를 게시하고 GitHub Actions로 빌드·테스트·배포를 자동화하는 레퍼런스  |  공식 문서: docs.github.com/pages

배포 구조 한눈에 보기

저장소의 정적 파일이 어떤 경로로 공개 URL이 되는지, 그리고 Actions 워크플로가 어떤 계층으로 실행되는지를 한 그림으로 정리한다.

저장소 (repository)
├── 게시 소스 (Settings > Pages)            둘 중 하나 선택
│   ├── Deploy from a branch                  브랜치 + 폴더(root 또는 /docs)
│   │   ├── / (root)                          저장소 루트의 index.html
│   │   └── /docs                             docs 폴더의 index.html
│   └── GitHub Actions                        워크플로가 빌드 산출물을 배포
│
├── 공개 URL
│   ├── <owner>.github.io                     사용자/조직 사이트 (계정당 1개)
│   └── <owner>.github.io/<repo>/             프로젝트 사이트 (저장소당 1개)
│
└── .github/workflows/*.yml                 Actions 워크플로 정의
    └── jobs                                  runs-on 러너에서 실행
        └── steps                             uses(액션) 또는 run(셸)

1. GitHub Pages 게시

GitHub Pages는 저장소의 HTML/CSS/JS를 그대로 가져와 웹사이트로 게시하는 무료 정적 호스팅이다. 빌드 과정은 선택이며, AI로 만든 정적 웹앱을 손쉽게 공개하기에 적합하다.

GitHub Pages — 저장소를 웹사이트로 게시하는 정적 호스팅

저장소에 올린 정적 파일을 가져와 공개 URL로 서비스한다. 별도 서버 없이 무료로 호스팅되며, 빌드 도구를 쓰지 않으면 파일을 그대로 게시한다.

Settings > Pages 에서 게시 소스(Source)를 지정 → 저장 → 공개 URL 생성

<owner>.github.io — 사용자/조직 사이트

저장소 이름을 반드시 <owner>.github.io로 만들어야 하는 특수 사이트다. 계정(사용자/조직)당 1개만 가질 수 있고, 루트 도메인에 게시된다.

저장소 이름: octocat.github.io
공개 URL:    https://octocat.github.io

<owner>.github.io/<repository>/ — 프로젝트 사이트

일반 프로젝트 저장소에서 게시하는 사이트다. 저장소당 1개를 가질 수 있으며, URL은 저장소 이름이 하위 경로로 붙는다. 대부분의 실습은 이 형태를 쓴다.

저장소: octocat/my-site
공개 URL: https://octocat.github.io/my-site/

Deploy from a branch — 게시 소스(브랜치 방식)

Settings > Pages에서 "Deploy from a branch"를 선택하면 특정 브랜치의 파일을 그대로 게시한다. 소스 브랜치는 임의로 고를 수 있지만, 소스 폴더는 루트(/) 또는 /docs 둘 중 하나만 허용된다.

Settings > Pages > Source = "Deploy from a branch"
Branch = main,  Folder = / (root)  또는  /docs

GitHub Actions — 게시 소스(Actions 방식)

Settings > Pages에서 "GitHub Actions"를 선택하면 워크플로가 빌드 산출물을 아티팩트로 만들어 배포한다. React·Vite 등 빌드 도구를 쓰거나 임의 폴더를 게시하려면 이 방식이 필요하다.

Settings > Pages > Source = "GitHub Actions"
→ .github/workflows/*.yml 워크플로가 배포를 담당

.nojekyll — Jekyll 빌드 건너뛰기

Pages는 기본적으로 Jekyll로 빌드하므로 _로 시작하는 폴더(예: _next)를 무시할 수 있다. 게시 폴더(루트 등)에 빈 .nojekyll 파일을 두면 Jekyll 처리를 건너뛴다. 브랜치 방식에서 CSS/JS가 깨질 때 흔한 해결책이며, Actions 방식에서는 대개 불필요하다.

# 게시 폴더 루트에 빈 파일 생성
touch .nojekyll

2. Actions 워크플로

GitHub Actions는 .github/workflows/ 폴더의 YAML 파일로 정의하는 자동화 엔진이다. 푸시 같은 이벤트에 반응해 러너에서 단계(steps)를 실행한다.

워크플로 YAML 구조 — name·on·jobs·steps

워크플로는 .github/workflows/에 .yml/.yaml로 둔다. 최상위에 name, 트리거 on, jobs를 두고, 각 job은 runs-on(러너)과 steps를 가진다. step은 액션을 부르는 uses 또는 셸 명령 run 중 하나다.

name: GitHub Actions Demo
on: [push]
jobs:
  Explore:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Repo cloned to the runner."

actions/checkout@v4 — 러너에 저장소 체크아웃

러너 환경으로 저장소 코드를 가져오는 단계로, 거의 모든 워크플로의 첫 step에 들어간다. 이후 step들이 소스 파일에 접근하려면 반드시 필요하다.

- uses: actions/checkout@v4

actions/configure-pages@v5 — Pages 배포 설정 구성

Pages 배포에 필요한 환경 설정을 구성하는 액션이다. Actions 방식 게시 워크플로의 준비 단계로 사용한다.

- uses: actions/configure-pages@v5

actions/upload-pages-artifact@v3 — 배포 폴더를 아티팩트로 업로드

배포할 폴더를 Pages 아티팩트로 업로드한다. with: path:로 업로드할 디렉터리를 지정하며, 루트 전체는 '.', 빌드 산출물은 './dist'처럼 준다.

- uses: actions/upload-pages-artifact@v3
  with:
    path: '.'

actions/deploy-pages@v4 — 아티팩트를 실제로 배포

업로드된 Pages 아티팩트를 실제 사이트로 배포하는 마지막 단계다. id를 부여하면 배포 결과(예: page_url)를 다른 곳에서 참조할 수 있다.

- id: deployment
  uses: actions/deploy-pages@v4

트리거 + 권한 — on·permissions·environment·concurrency

Pages를 배포하는 job은 표준 트리거와 권한 설정을 갖춘다. on: push로 자동 실행하고, 토큰 권한으로 contents: read·pages: write·id-token: write를 부여한다. environment: github-pages와 concurrency: group: "pages"가 표준 패턴이다.

on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: "pages"
  cancel-in-progress: false

Pages 배포 액션 세트 — 네 액션의 역할 정리

Actions 방식 게시는 아래 네 액션을 조합해 구성한다. 순서대로 체크아웃 → 설정 → 업로드 → 배포로 이어진다.

3. 시크릿·CLI·파이프라인

시크릿으로 민감 값을 안전하게 주입하고, gh CLI로 워크플로를 실행·관찰하며, 빌드·테스트·배포를 하나의 파이프라인으로 묶는다.

${{ secrets.X }} — Actions 시크릿 참조

Settings > Secrets and variables > Actions에 저장한 비밀 값을 워크플로에서 ${{ secrets.X }}로 참조한다. 키·토큰을 코드에 하드코딩하지 말고, env:로 step에 주입한다.

- name: Use a secret
  env:
    API_KEY: ${{ secrets.API_KEY }}
  run: ./deploy.sh

gh secret set — CLI로 시크릿 등록

웹 UI 대신 gh CLI로 시크릿을 저장할 수 있다. 등록한 이름을 워크플로에서 secrets.<NAME>으로 참조한다.

gh secret set API_KEY

gh workflow — 워크플로 목록·실행

워크플로를 CLI에서 조회하거나 수동 실행한다. gh workflow run은 workflow_dispatch 트리거가 있는 워크플로를 특정 브랜치(--ref)로 실행한다.

gh workflow list
gh workflow run deploy.yml --ref main

gh run — 실행 관찰·로그 확인

워크플로 실행 내역을 보고 진행 상황을 실시간으로 지켜보거나 실패 로그를 확인한다. gh run watch <id>로 진행을, gh run view <id> --log로 로그를 본다.

gh run list
gh run watch <id>
gh run view <id> --log

빌드+테스트+배포 파이프라인 — needs로 job 연결

여러 job을 needs로 연결해 순서를 강제한다. build job이 의존성 설치·테스트·빌드를 수행하면, deploy job은 needs: build로 build 성공 시에만 실행된다. 테스트가 실패하면 배포가 중단된다.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm test
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

actions/setup-node@v4 — Node.js 환경 준비

러너에 Node.js를 설치·구성하는 액션으로, npm ci·npm test·npm run build 같은 Node 기반 빌드 단계 앞에 둔다.

- uses: actions/setup-node@v4
- run: npm ci

게시 소스 선택 기준 — 브랜치 방식 vs Actions 방식

두 게시 방식은 빌드 필요 여부와 게시 폴더 자유도에서 갈린다. 단순 정적 파일이면 브랜치 방식, 빌드 도구·임의 폴더면 Actions 방식이 적합하다.

Pages 사용 한도 — soft 한도 요약

Pages에는 권장(soft) 한도가 있다. 정적 호스팅이 목적이므로 대용량·고트래픽 서비스에는 적합하지 않다.

1. 사이트 크기: 1GB 이하 권장
2. 대역폭: 월 100GB
3. 빌드: 시간당 10회, 배포 타임아웃 10분

💡 핵심 한 줄: 단순 정적 파일은 브랜치 방식으로 바로 게시하고, 빌드·테스트가 필요하면 Actions 방식 파이프라인으로 자동화한다.

참고 링크

• 📖 GitHub Pages 문서 — docs.github.com/en/pages
• ⚙️ GitHub Actions 문서 — docs.github.com/en/actions
• 📦 actions/starter-workflows
• 📦 actions/deploy-pages · actions/upload-pages-artifact
• 🔧 gh workflow · gh run

GitHub Pages·Actions 2026-06 기준 | 2026년 6월