jdevalk/skills

Astro GitHub Actions

이 스킬은 GitHub Actions를 사용하여 Astro 사이트를 위한 포괄적인 CI/CD 파이프라인을 설정하는 데 도움을 줍니다. 목표는 작성자가 수동 작업을 줄이고 더 높은 품질의 사이트를 제공할 수 있도록 돕는 것입니다: 병합 전에 타입 오류 포착, 깨진 링크 플래그 지정, 빌드 검증, 배포 자동화.

이 스킬이 다루는 내용

건강한 Astro 프로젝트가 가져야 할 여러 범주의 워크플로우가 있습니다. 모든 사이트에 모든 워크플로우가 필요한 것은 아닙니다. 적절한 조합은 프로젝트에 TypeScript, 사용자 정의 컴포넌트, 콘텐츠 컬렉션, 테스트가 있는지, 그리고 어디에 배포하는지에 따라 달라집니다. 여러분의 역할은 어떤 워크플로우가 관련 있는지 파악하고 설정하는 것입니다.

워크플로우 범주는 다음과 같습니다:

1. 타입/콘텐츠 검사 — astro check (TypeScript + 콘텐츠 컬렉션 스키마 유효성 검사)
2. 코드 품질 — ESLint 및 Prettier
3. 빌드 검증 — astro build가 깔끔하게 실행되는지 확인
4. 테스트 — Vitest를 사용한 단위 및 컴포넌트 테스트
5. 품질 게이트 — Lighthouse CI (성능, 접근성, SEO, 모범 사례)
6. 링크 확인 — 빌드된 사이트의 깨진 링크 감지
7. 보안 — 종속성 취약점에 대한 npm audit
8. 배포 — GitHub Pages, Cloudflare Pages, Netlify 또는 Vercel

각 워크플로우의 상세 설정(사용 가능한 YAML 템플릿 및 설정 파일 포함)은 references/workflows.md를 참조하세요.

요청 처리 방법

1단계: 프로젝트 이해

워크플로우 파일을 작성하기 전에, 작업 중인 내용을 파악하세요:

• TypeScript를 사용하나요? tsconfig.json과 .ts/.astro 파일이 있는지 확인하세요. 거의 모든 Astro 프로젝트는 astro check를 실행해야 하지만, 특히 .astro 프론트매터, 콘텐츠 컬렉션 스키마 또는 src/에 TypeScript가 있는 경우 가치가 가장 높습니다.
• 콘텐츠 컬렉션을 사용하나요? src/content/config.ts 또는 src/content.config.ts가 있는지 확인하세요. 있다면 astro check가 스키마를 검증하여 추가 가치를 제공합니다.
• 테스트가 있나요? tests/, __tests__/, *.test.ts 또는 vitest.config.ts가 있는지 확인하세요. 있다면 Vitest 워크플로우를 설정하세요. 없다면 테스트를 추가하는 것이 유용할 것이라고 언급하되 강요하지 마세요.
• 패키지 매니저는 무엇인가요? pnpm-lock.yaml, yarn.lock 또는 package-lock.json을 확인하세요. 워크플로우의 설치 명령어를 일치시키세요 (pnpm i --frozen-lockfile, yarn install --frozen-lockfile 또는 npm ci).
• 어디에 배포하나요? wrangler.toml (Cloudflare), netlify.toml (Netlify), vercel.json (Vercel)을 찾거나 직접 물어보세요. 대부분의 호스트는 Actions 없이 자동으로 배포하는 자체 GitHub 앱을 가지고 있습니다. 사용자가 실제로 Actions로 처리하기를 원하는 경우에만 배포 워크플로우를 설정하세요 (일반적으로 GitHub Pages 또는 자체 호스팅).
• 빌드 단계가 있나요? Astro는 항상 그렇습니다 (astro build) — 하지만 package.json의 스크립트가 표준 astro build인지 사용자 정의인지 확인하세요.
• SSR인가요, 정적인가요? astro.config.*에서 output: 'server' 또는 어댑터 임포트를 확인하세요. SSR 프로젝트는 다르게 배포되며 (Cloudflare/Netlify/Vercel 어댑터) GitHub Pages에 전혀 배포하지 못할 수도 있습니다.

2단계: 워크플로우 세트 추천

발견한 내용을 기반으로 어떤 워크플로우를 설정할지 추천하세요. 대부분의 Astro 사이트에 좋은 기본값:

• astro check (거의 항상 — Astro에서 가장 가치 있는 검사)
• 빌드 검증 (거의 항상 — astro check가 놓칠 수 있는 통합 회귀를 잡아냄)
• ESLint + Prettier (설정 파일이 있거나 사용자가 원하는 경우)
• Lighthouse CI (공개 URL이 있는 콘텐츠 사이트에 좋음)
• 링크 검사기 (콘텐츠가 많은 사이트에 좋음)
• npm audit (비용이 낮아 거의 항상 가치 있음)

그리고 조건부:

• Vitest 테스트 (테스트가 있는 경우)
• 배포 워크플로우 (사용자가 Actions 기반 배포를 원하는 경우에만 — 대부분의 Astro 호스트는 자체 GitHub 앱을 사용함)

3단계: 워크플로우 파일 생성

각 워크플로우를 .github/workflows/에 별도의 YAML 파일로 생성하세요. 하나의 모놀리식 워크플로우 대신 별도의 파일을 사용하면 PR에서 더 명확한 피드백을 제공하고 (각 검사가 독립적으로 표시됨) 개별 검사를 활성화/비활성화하기 더 쉽습니다.

references/workflows.md의 템플릿을 시작점으로 사용하되, 특정 프로젝트에 맞게 조정하세요. 일반적인 조정 사항으로는 패키지 매니저, Node 버전, 빌드 아티팩트 경로 및 배포 대상을 조정하는 것이 포함됩니다.

4단계: 지원 설정 파일 생성

설정한 워크플로우에 따라 다음 파일도 필요할 수 있습니다:

• eslint.config.js — eslint-plugin-astro가 포함된 ESLint 플랫 설정
• .prettierrc 및 .prettierignore — prettier-plugin-astro가 포함된 Prettier 설정
• lighthouserc.json — Lighthouse CI 어설션
• lychee.toml — 링크 검사기 설정 (lychee 사용 시)
• vitest.config.ts — Vitest 설정

5단계: 시크릿 설정 알림

배포 워크플로우를 추가하는 경우, 필요한 리포지토리 시크릿을 사용자에게 알리세요:

• GitHub Pages — 없음 (GITHUB_TOKEN 사용)
• Cloudflare Pages — CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
• Netlify — NETLIFY_AUTH_TOKEN, NETLIFY_SITE_ID
• Vercel — VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID

사용자를 안내하세요: 리포지토리 설정 > 시크릿 및 변수 > Actions > 새 리포지토리 시크릿.

Cloudflare, Netlify 및 Vercel의 경우: 해당 플랫폼은 빌드 + 배포 + PR 미리보기를 자동으로 처리하는 자체 GitHub 앱을 제공한다는 점도 상기시키세요. Actions 기반 배포는 일반적으로 배포를 테스트 결과에 의존해야 하거나, 플랫폼에 없는 시크릿으로 빌드를 실행해야 하거나, 리포지토리 루트가 아닌 다른 경로에서 배포해야 하는 경우에만 가치가 있습니다.

명명 규칙

각 워크플로우의 기능을 명확히 알 수 있도록 설명적인 워크플로우 파일 이름을 사용하세요:

• astro-check.yml — astro check (타입 + 콘텐츠 스키마)
• lint.yml — ESLint
• format.yml — Prettier 확인
• build.yml — 빌드 검증
• test.yml — Vitest
• lighthouse.yml — Lighthouse CI
• links.yml — 깨진 링크 검사기
• security.yml — npm audit
• deploy.yml — 호스트에 배포

중요한 세부 사항

Node.js 버전: Astro는 Node 18.20.8+, 20.3.0+ 또는 22.0.0+이 필요합니다. Node 22를 기본값으로 사용하세요 — 이는 Astro의 안정적인 대상과 일치하며 많은 어댑터가 이를 기준으로 테스트됩니다. actions/checkout@v5 및 actions/setup-node@v5를 사용하세요.

패키지 매니저 감지: 항상 잠금 파일과 일치시키세요. pnpm-lock.yaml → pnpm/action-setup@v4 및 pnpm install --frozen-lockfile 사용. yarn.lock → yarn install --frozen-lockfile. package-lock.json → npm ci. CI에서 npm install을 사용하지 마세요 (비결정적이며 느림).

브랜치 이름: 대부분의 Astro 리포지토리는 기본 브랜치로 main을 사용하지만, 트리거를 작성하기 전에 실제 리포지토리를 확인하세요.

Astro 어댑터 및 SSR: 프로젝트가 @astrojs/cloudflare, @astrojs/netlify 또는 @astrojs/vercel을 사용하는 경우 빌드 출력이 정적 dist/ 디렉토리가 아닐 수 있습니다. Cloudflare 어댑터는 dist/와 _worker.js를 출력합니다. Vercel은 .vercel/output/을 출력합니다. Netlify는 .netlify/를 출력합니다. 배포 아티팩트 경로를 그에 맞게 조정하세요.

astro check에는 @astrojs/check와 typescript가 필요합니다: 둘 다 설치되어 있어야 합니다. devDependencies에 없으면 워크플로우가 실패합니다. package.json에 이미 있는 경우에만 npm ci의 일부로 추가하세요 — 그렇지 않으면 워크플로우에서 명시적으로 설치해야 합니다.

PR의 Lighthouse CI: 모든 PR에서 Lighthouse를 실행하면 성능 회귀를 조기에 잡을 수 있습니다. treosh/lighthouse-ci-action이 표준입니다. 공개 미리보기 URL(Cloudflare Pages, Netlify, Vercel)의 경우 Lighthouse를 배포 미리보기 URL에 지정하세요 — 현실적인 수치를 제공합니다. 내부 전용 설정의 경우 실행기 내에서 로컬로 빌드하고 제공하세요.

소스가 아닌 빌드 출력물에 대한 링크 확인: 빌드된 dist/ 디렉토리(또는 배포된 미리보기 URL)에서 링크 검사기를 실행하세요 — Markdown 소스에서 실행하면 생성된 경로와 사이트맵 링크를 놓칠 수 있습니다.

Actions 배포보다 플랫폼의 GitHub 앱 선호: Cloudflare Pages, Netlify 및 Vercel은 모두 수동으로 만든 Action보다 PR 미리보기, 브랜치 배포 및 롤백을 더 잘 처리하는 자체 GitHub 앱을 가지고 있습니다. 먼저 GitHub 앱을 추천하고, 사용자가 그렇게 해야 하는 특별한 이유가 있는 경우에만 Actions 배포를 제안하세요.