Communitygithub.com

tangshengming/personal_website

이미 생성된 정적 개인 웹사이트를 GitHub Pages에 배포합니다. 사용자가 웹사이트 배포, 생성된 Astro 사이트 게시, GitHub Pages 설정, GitHub Actions 배포 워크플로우 설명 또는 업데이트, 또는 푸시 후 배포된 사이트 확인을 요청할 때 사용하세요.

personal_website란 무엇인가요?

이 스킬은 Astro로 생성된 정적 개인 웹사이트를 GitHub Pages에 자동으로 배포하는 프로세스를 안내합니다. 사용자가 사이트 배포를 요청하면, 사전에 생성된 소스 파일을 GitHub 저장소에 커밋하고, GitHub Actions 워크플로우를 통해 빌드 및 배포까지 수행합니다. 이 스킬은 이미 웹사이트가 존재한다고 가정하므로, 사용자가 요청하지 않는 한 웹사이트를 재설계하지 않습니다. 지원하는 플랫폼은 Astro(정적 사이트 생성기)와 GitHub Pages(호스팅)이며, GitHub Actions 워크플로우는 `withastro/action`과 `actions/deploy-pages`를 사용하여 간단하게 구성됩니다. 또한 로컬 개발 환경과 GitHub Pages 빌드 환경에서의 `base` 경로 설정을 자동으로 처리하는 방법을 제시하고, 배포 전후의 확인 단계와 문제 해결 방법을 상세히 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tangshengming/personal_website/tree/HEAD/.codex/skills/deploy-website

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

웹사이트 배포

개요

이 스킬은 이미 생성된 웹사이트를 GitHub Pages에 배포하는 과정을 안내합니다. 예상되는 프로젝트는 GitHub 저장소에 저장된 Astro 정적 사이트이며, 소스 파일은 커밋되어 있고 배포는 GitHub Actions로 처리됩니다.

이 스킬은 웹사이트 자체가 이미 존재한다고 가정합니다. 사용자가 요청하지 않는 한 웹사이트를 재설계하지 마십시오.

배포 모델

현재 개인 웹사이트 워크플로우에는 다음 설정을 사용하세요.

  • Git으로 소스 코드를 추적합니다.
  • node_modules/, dist/, .astro/, tmp/ 등 생성되거나 의존성 폴더는 무시합니다.
  • npm.cmd run build로 사이트를 빌드합니다.
  • GitHub Actions에서 GitHub Pages로 배포합니다.
  • 로컬 개발은 http://localhost:4321/에서 유지합니다.
  • 프로젝트 Pages URL(예: https://USERNAME.github.io/REPOSITORY/)의 경우 GitHub Actions 빌드 중에만 Astro base 경로를 사용합니다.

배포 전

간단한 명령으로 준비 상태를 확인하세요.

git status
npm.cmd run build

다음 파일 또는 설정이 있는지 확인하세요.

  • package.json
  • astro.config.mjs
  • .gitignore
  • .github/workflows/deploy.yml
  • src/
  • public/

이 프로젝트의 경우 astro.config.mjs는 로컬 및 GitHub Pages 빌드를 모두 지원해야 합니다. 예:

import { defineConfig } from "astro/config";

const isGithubPagesBuild = process.env.GITHUB_ACTIONS === "true";

export default defineConfig({
  site: "https://USERNAME.github.io",
  base: isGithubPagesBuild ? "/REPOSITORY" : "/",
});

로컬 공개 자산이나 내부 페이지에 링크할 때 Astro 페이지/레이아웃에서 URL 헬퍼를 사용하세요.

const base = import.meta.env.BASE_URL;
const url = (path: string) => {
  const normalizedBase = base.endsWith("/") ? base : `${base}/`;
  const normalizedPath = path.replace(/^\/+/g, "");

  return `${normalizedBase}${normalizedPath}`;
};

GitHub Actions 워크플로우

다음과 같은 Pages 워크플로우를 사용하세요.

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7
      - name: Build with Astro
        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

필요한 경우 액션을 간단히 설명하세요.

  • actions/checkout@v7: GitHub Actions 러너에 저장소를 다운로드합니다.
  • withastro/action@v6: 의존성을 설치하고, Astro 사이트를 빌드하며, Pages 아티팩트를 준비합니다.
  • actions/deploy-pages@v5: 빌드된 아티팩트를 GitHub Pages에 게시합니다.

@vN 접미사는 액션의 주요 버전을 고정합니다.

저장소 및 커밋 단계

사용자가 배포 준비가 된 소스 변경 사항을 커밋하고 푸시하도록 안내하세요.

git status
git add .
git commit -m "Prepare website deployment"
git push origin main

Git에서 LF will be replaced by CRLF와 같은 줄 끝 경고가 표시되면, 이는 Windows 줄 끝 정규화 경고이며 일반적으로 배포를 차단하지 않는다고 설명하세요.

Git에서 구성된 사용자 ID가 없다고 보고하면, 커밋하기 전에 저장소 또는 전역 ID를 구성하세요. 개인정보 보호가 중요한 경우 사용자의 GitHub noreply 이메일을 사용하세요.

GitHub Pages 설정

GitHub에서 사용자를 안내하세요.

  1. GitHub에서 저장소를 엽니다.
  2. Settings로 이동합니다.
  3. Pages로 이동합니다.
  4. Build and deployment 아래에서 Source를 GitHub Actions로 설정합니다.
  5. GitHub에 저장 버튼이 표시되면 저장합니다.
  6. Actions 탭으로 이동하여 최신 배포 실행을 엽니다.
  7. 워크플로우가 성공할 때까지 기다립니다.
  8. GitHub에서 표시하는 Pages URL을 엽니다.

프로젝트 사이트의 경우 예상 URL은 일반적으로 다음과 같습니다.

https://USERNAME.github.io/REPOSITORY/

확인

배포 후 다음을 확인하세요.

  • 홈페이지가 로드됩니다.
  • 탐색 링크가 작동합니다.
  • 이미지가 로드됩니다.
  • CV PDF와 같은 다운로드 가능한 파일이 올바르게 열립니다.
  • 브라우저 URL에 프로젝트 Pages의 저장소 경로가 포함됩니다.
  • 생성된 HTML에 /REPOSITORYprojects, /REPOSITORYprofile.jpg, 또는 /REPOSITORYfile.pdf와 같은 잘못된 경로가 나타나지 않습니다.

배포된 사이트가 손상되었지만 로컬 미리보기는 정상인 경우, 먼저 base-path 처리를 검사하세요.

GitHub Actions가 실패하면 실패한 단계를 검사하세요.

  • 체크아웃 실패: 저장소 또는 권한 문제.
  • 설치/빌드 실패: 의존성, Astro 또는 소스 코드 문제.
  • 배포 실패: GitHub Pages 소스/권한/설정 문제.

완료 기준

다음 조건을 만족하면 배포 작업이 완료된 것으로 간주합니다.

  • 로컬 빌드가 통과되었습니다.
  • 소스 변경 사항이 커밋되고 푸시되었습니다.
  • GitHub Pages 소스가 GitHub Actions로 설정되었습니다.
  • Actions 배포 실행이 성공했습니다.
  • 공개 Pages URL이 웹사이트를 올바르게 로드합니다.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

관련 스킬