배포·자동화 실습 예시

정적 사이트 게시부터 Actions 자동 배포·CI 파이프라인까지 난이도별로 따라하는 가이드 | ← 레퍼런스 문서로 돌아가기

대상 범위GitHub Pages·Actions 2026-06 기준, actions/* 권장 버전 태그

이 파일의 목적매뉴얼의 개념을 실제 게시·배포 시나리오로 재현 가능하게 보완

레퍼런스 문서Deploy_Manual.html — 각 시나리오에서 링크로 연결됩니다

작성일2026년 6월 16일

● 초급 Getting Started 정적 파일을 처음으로 웹에 올려 공개 URL을 얻어 본다

G-1 초급 정적 HTML을 Pages로 게시하기 (브랜치 방식)

AI로 index.html 한 장짜리 소개 페이지를 만들었다. 별도 서버 없이 공개 URL로 누구나 볼 수 있게 하고 싶다. 빌드 도구는 쓰지 않고, 새로 만든 공개 저장소에 파일을 그대로 올려 게시하는 가장 단순한 방법을 쓴다.

사용 요소

GitHub Pages Deploy from a branch .nojekyll

단계별 실행

공개 저장소 루트에 index.html 푸시
새 공개 저장소를 만들고, 저장소 루트(/)에 index.html을 올린다. (전제: main 브랜치 사용)
```
git add index.html
git commit -m "Add landing page"
git push origin main
```
Settings > Pages에서 브랜치 게시 설정
Settings > Pages로 가서 Source를 "Deploy from a branch"로, Branch를 main, Folder를 / (root)로 지정하고 Save한다.
```
Settings > Pages
  Source = "Deploy from a branch"
  Branch = main   Folder = / (root)
  → Save
```
공개 URL 확인
잠시 후 프로젝트 사이트 URL에서 페이지가 보이는지 확인한다. <user>·<repo>를 본인 값으로 바꾼다.
```
https://<user>.github.io/<repo>/
```

브랜치 방식은 지정한 브랜치·폴더의 파일을 그대로 가져와 게시한다. 게시 폴더는 루트(/) 또는 /docs 둘 중 하나만 허용되며, 다른 폴더를 쓰려면 Actions 방식이 필요하다.

Free 플랜에서는 공개 저장소만 게시할 수 있다. 또한 저장소가 비공개여도 게시된 사이트는 누구나 접근할 수 있으므로 API 키 등 민감 정보를 페이지에 넣지 않는다.

CSS/JS가 깨져 보이면 게시 폴더 루트에 빈 .nojekyll 파일을 추가하고 다시 푸시한다. Pages의 기본 Jekyll 빌드가 _로 시작하는 폴더를 무시하는 문제를 막아 준다.

● 중급 Daily Workflow 푸시할 때마다 워크플로가 자동으로 사이트를 배포하게 만든다

D-1 중급 Actions로 푸시 시 자동 배포하기

사이트를 수정할 때마다 손으로 게시 설정을 만지는 게 번거롭다. main에 푸시하면 GitHub Actions가 알아서 사이트를 다시 배포하도록 자동화한다. (전제: 공개 저장소, 루트에 정적 파일이 있음, gh CLI 로그인 완료)

사용 요소

GitHub Actions (게시 소스) upload-pages-artifact@v3 deploy-pages@v4 gh run watch

단계별 실행

게시 소스를 GitHub Actions로 전환
Settings > Pages에서 Source를 "GitHub Actions"로 바꾼다. 이제 워크플로가 배포를 담당한다.
```
Settings > Pages
  Source = "GitHub Actions"
```

deploy.yml 워크플로 작성

.github/workflows/deploy.yml을 만들고 아래 내용을 그대로 넣는다. main 푸시와 수동 실행(workflow_dispatch) 모두에서 동작한다.

name: Deploy static content to Pages
on:
  push:
    branches: [main]
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: "pages"
  cancel-in-progress: false
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: '.'
      - id: deployment
        uses: actions/deploy-pages@v4

푸시하고 실행 관찰
워크플로 파일을 푸시하면 Actions 탭에서 자동으로 실행된다. gh run watch로 진행 상황을 실시간으로 본다.
```
git add .github/workflows/deploy.yml
git commit -m "Add Pages deploy workflow"
git push origin main
gh run watch
```

푸시 이벤트가 워크플로를 트리거하면 러너가 저장소를 체크아웃하고(checkout), Pages 설정을 구성한 뒤(configure-pages), 루트 폴더를 아티팩트로 업로드하고(upload-pages-artifact, path: '.'), deploy-pages가 실제 사이트로 배포한다. concurrency: group: "pages"로 동시 배포 충돌을 막는다.

토큰 권한 pages: write·id-token: write는 Pages 배포에 필수다. 누락하면 deploy-pages 단계가 권한 오류로 실패한다. 또한 actions/* 버전 태그는 권장값이며 최신값으로 갱신될 수 있다.

● 고급 Power User 빌드와 테스트를 거쳐 통과한 산출물만 배포하는 CI/CD 파이프라인

P-1 고급 빌드+테스트+배포 파이프라인 구성하기

Node 기반 프런트엔드 프로젝트를 운영한다. 테스트가 통과한 빌드 산출물(./dist)만 사이트로 배포되도록, 빌드·테스트를 한 job에서 끝낸 뒤 별도 deploy job이 그 결과만 배포하게 만든다. (전제: 공개 저장소, package.json에 test·build 스크립트, 빌드 산출물은 ./dist)

사용 요소

setup-node@v4 needs: build upload-pages-artifact@v3 gh run view --log

단계별 실행

build job: 설치·테스트·빌드·업로드

setup-node로 Node를 준비하고 npm ci → npm test → npm run build를 실행한 뒤, ./dist를 Pages 아티팩트로 업로드한다. 테스트가 실패하면 여기서 멈춘다.

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 job: needs로 build에 연결
deploy job에 needs: build를 두어 build가 성공할 때만 실행되게 한다. deploy-pages가 업로드된 ./dist 아티팩트를 배포한다. (배포 권한 블록은 중급 D-1과 동일하게 둔다)
```
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4
```
실행 확인, 실패 시 로그 분석
실행 목록을 보고 진행을 관찰한다. 실패하면 해당 실행 ID의 로그를 열어 어느 단계(테스트/빌드)에서 멈췄는지 확인한다.
```
gh run list
gh run watch
gh run view <id> --log
```

두 job은 needs: build 의존성으로 순차 실행된다. build가 npm test에서 실패하면 deploy job은 시작조차 하지 않으므로, 깨진 산출물이 사이트로 나가지 않는다. 통과한 ./dist만 아티팩트로 넘어가 deploy-pages가 게시한다.

빌드 결과가 정상인데 사이트가 깨지면, 빌드 산출물에 _next 같은 _ 시작 폴더가 있는지 확인하고 필요 시 산출물 루트에 빈 .nojekyll을 포함시킨다. 다만 Actions 방식 배포에서는 대개 불필요하다.

함께 보기: 자동 배포 골격은 중급 D-1, 시크릿 주입·gh 운영 명령은 매뉴얼 3. 시크릿·CLI·파이프라인을 참고한다.

GitHub Pages·Actions 2026-06 기준 | 2026년 6월 16일 작성
← 배포·자동화 매뉴얼