Preflight.sh

Preflight.sh는 코드베이스를 스캔하여 출시 준비 상태를 확인하는 명령줄 도구입니다. 프로덕션에 배포하기 전에 누락된 구성, 통합 문제, 보안 우려 사항, SEO 메타데이터 누락 및 기타 일반적인 실수를 식별합니다.

프로덕션에서 망신을 당하지 마세요. 그냥 명령을 실행하세요.

설치

Homebrew (macOS/Linux)

brew install preflightsh/preflight/preflight

npm

npm install -g @preflightsh/preflight

Go

go install github.com/preflightsh/preflight@latest

Docker

docker pull ghcr.io/preflightsh/preflight

셸 스크립트

curl -sSL https://preflight.sh/install.sh | sh

수동 다운로드

GitHub Releases에서 최신 릴리스를 다운로드하세요.

빠른 시작

# 프로젝트 디렉터리에서 초기화
cd your-project
preflight init

# 모든 검사 실행
preflight scan

# 특정 디렉터리 스캔
preflight scan /path/to/project

# 상세 출력으로 실행 (각 검사에 매칭된 파일 표시)
preflight scan --verbose
preflight scan -v  # 축약형

# JSON 출력의 CI 모드로 실행
preflight scan --ci --format json

# 빠른 반복을 위해 특정 검사만 실행하거나 일부 건너뛰기
# (일회성; `preflight ignore`와 달리 preflight.yml을 변경하지 않음)
preflight scan --only seo_meta,og_twitter
preflight scan --skip vulnerability,secrets

# 검사 무시
preflight ignore sitemap

# 검사 무시 해제
preflight unignore sitemap

# 모든 검사 ID 나열
preflight checks

에이전트 스킬

이 저장소에는 skills/preflight/SKILL.md에 skills.sh 호환 에이전트 스킬이 포함되어 있습니다. 코딩 에이전트에게 반복 가능한 Preflight 워크플로를 제공합니다: preflight.yml 검사, CI 안전 스캔 실행, 결과 분류, 안전하지 않은 무시 방지, 검증 재실행, 잔여 출시 위험 보고.

이 저장소에서 스킬 목록 보기:

# Bun 사용
bunx --yes skills add preflightsh/preflight --list

# 또는 npm 사용
npx --yes skills add preflightsh/preflight --list

Preflight 스킬만 설치:

# Bun 사용
bunx --yes skills add preflightsh/preflight --skill preflight

# 또는 npm 사용
npx --yes skills add preflightsh/preflight --skill preflight

대시보드 및 AI 제안

Preflight는 계정 없이도 명령줄에서 완전히 사용할 수 있습니다. 선택적 대시보드인 app.preflight.sh는 스캔의 호스팅된 기록과 각 결과에 대한 AI 생성 수정 제안을 추가합니다. 코드는 절대 머신을 떠나지 않습니다: 스캔은 로컬에서 실행되며, 게시할 때 결과의 수정된 요약(검사 ID, 상태, 메시지 — 비밀 값이나 파일 내용은 절대 아님)만 전송됩니다.

무료 계정을 만든 후 CLI를 연결하세요:

preflight auth login    # 브라우저를 열어 이 CLI를 인증
preflight auth status   # 로그인한 사용자 표시
preflight auth logout   # 저장된 자격 증명 제거

--publish로 스캔을 대시보드에 게시하세요. 실행을 볼 수 있는 링크가 출력됩니다. 게시는 최선 노력 방식입니다: 오프라인이거나 로그인하지 않은 경우에도 스캔은 계속 실행되고 정상적으로 종료됩니다.

preflight scan --publish

대시보드에서 각 실행의 통과/경고/실패 분석, 전체 결과 목록, 프로젝트별 기록을 확인하여 배포 간 변경 사항을 볼 수 있습니다.

터미널에서 preflight history로 해당 기록을 읽을 수도 있습니다:

preflight history                       # 프로젝트 전체의 최근 실행
preflight history --here                # 현재 프로젝트의 실행만
preflight history <run-id>              # 단일 실행의 전체 검사 결과
preflight history --here --format json  # 에이전트용 기계 판독 가능 형식

preflight auth login이 필요합니다. --here는 게시 시 사용되는 것과 동일한 키인 git 원격을 기준으로 실행을 현재 저장소에 매칭합니다.

게시된 실행에서 실패하거나 경고가 있는 검사를 열어 감지된 스택에 맞춘 단계별 수정 사항을 생성하세요. 복사 가능한 명령과 코드가 포함됩니다.

무료는 월 5회 게시 실행을 포함합니다.
자체 키 사용: 대시보드 설정에서 OpenAI 또는 Anthropic API 키를 추가하면 게시가 무료로 무제한 유지됩니다(공급자에게 직접 비용 지불).
관리형 ($5/월): AI 비용을 당사가 부담하며 실행이 무제한이고 API 키가 필요 없습니다.

검사 항목

검사	설명
ENV 일치	`.env`와 `.env.example`을 비교하여 누락된 변수 확인
헬스 엔드포인트	사이트 접근 가능 여부 확인; `/health`, `/healthz`, `/api/health` 자동 감지 또는 루트로 대체
취약점 스캔	종속성 취약점 확인 (bundle audit, npm audit 등)
SEO 메타데이터	title, description, Open Graph 태그 확인
OG 및 Twitter 카드	og:image, twitter:card 및 소셜 공유 메타데이터 검증
표준 URL	표준 링크 태그 존재 여부 확인
뷰포트	모바일용 올바른 viewport 메타 태그 확인
Lang 속성	접근성을 위한 html lang 속성 검증
구조화된 데이터	JSON-LD Schema.org 마크업 확인
보안 헤더	프로덕션 및 스테이징 모두에서 HSTS, CSP, X-Content-Type-Options 검증
SSL 인증서	SSL 유효성 확인 및 만료 전 경고
WWW 리디렉션	www/비-www가 표준 URL로 리디렉션되는지 확인
이메일 인증	이메일 전달성을 위한 SPF/DMARC DNS 레코드 확인 (선택)
비밀 스캔	코드에서 유출된 API 키 및 자격 증명 찾기
디버그 문	코드에 남아 있는 console.log, var_dump, debugger 감지
오류 페이지	사용자 정의 404/500 오류 페이지 확인
이미지 최적화	로드 시간을 저하시키는 대용량 이미지(>500KB) 찾기
법적 페이지	개인정보 보호정책 및 서비스 약관 페이지 확인
쿠키 동의	쿠키 동의 솔루션 감지 (GDPR/CCPA 준수)
파비콘 및 아이콘	favicon, apple-touch-icon (.png, .webp, .svg) 및 웹 매니페스트 확인
robots.txt	robots.txt 존재 및 콘텐츠 확인
sitemap.xml	사이트맵 존재 또는 생성기 확인
llms.txt	LLM 크롤러 안내 파일 확인
ads.txt	광고 지원 사이트용 ads.txt 검증 (선택)
humans.txt	팀을 표시하는 humans.txt 확인 (선택)
IndexNow	더 빠른 검색 색인을 위한 IndexNow 키 파일 확인 (선택)
LICENSE	라이선스 파일 확인 (선택, 오픈 소스 프로젝트용)

지원 서비스 (72)

Preflight는 다음 서비스의 구성을 자동 감지하고 검증합니다:

결제

Stripe, PayPal, Braintree, Paddle, LemonSqueezy

오류 추적 및 모니터링

Sentry, Bugsnag, Rollbar, Honeybadger, Datadog, New Relic, LogRocket

이메일 및 뉴스레터

Postmark, SendGrid, Mailgun, AWS SES, Resend, Mailchimp, Kit, Beehiiv, AWeber, ActiveCampaign, Campaign Monitor, Drip, Klaviyo, Buttondown

분석

Plausible, Fathom, Umami, Fullres Analytics, Datafa.st Analytics, Google Analytics, PostHog, Mixpanel, Amplitude, Segment, Hotjar

인증

Auth0, Clerk, WorkOS

채팅

Intercom, Crisp

알림

Slack, Discord, Twilio

인프라

Firebase, Supabase, Redis, Sidekiq, RabbitMQ, Elasticsearch, Convex

스토리지 및 CDN

AWS S3, Cloudinary, Cloudflare

검색

Algolia

SEO

IndexNow

AI / LLM

OpenAI, Anthropic Claude, Google AI (Gemini), Mistral, Cohere, Replicate, Hugging Face, Grok (X/Twitter), Perplexity, Together AI

구성

Preflight는 프로젝트 루트의 preflight.yml 파일을 사용합니다:

projectName: my-app
stack: rails  # rails, next, react, vite, laravel 등

urls:
  staging: "https://staging.example.com"
  production: "https://example.com"

services:
  stripe:
    declared: true
  sentry:
    declared: true

checks:
  envParity:
    enabled: true
    envFile: ".env"
    exampleFile: ".env.example"

  healthEndpoint:
    enabled: true
    path: "/health"  # 선택 사항 - 설정하지 않으면 일반적인 경로를 자동 감지

  stripeWebhook:
    enabled: true
    url: "https://api.example.com/webhooks/stripe"  # 선택 사항 - GET으로 프로브; 404 또는 응답 없음이 보고됨

  seoMeta:
    enabled: true
    mainLayout: "app/views/layouts/application.html.erb"

  security:
    enabled: true

  secrets:
    enabled: true
    # 비밀 스캔용 파일별 허용 목록. 전체 검사를 비활성화하지 않고
    # 개별 결과(예: 리퍼러 제한 공개 키)를 억제하는 데 사용합니다.
    allowlist:
      - path: web/js/golden-hour.js
        fingerprint: "sha256:<hex>"   # 권장 — 정확한 비밀에 고정
        reason: "HTTP-리퍼러 제한 Google Timezone 키"
      - path: "web/tools/**/*.php"    # doublestar 글로브 지원

  indexNow:
    enabled: true
    key: "your32characterhexkeyhere00000"

  emailAuth:
    enabled: true  # 선택 사항, 프로덕션 도메인의 SPF/DMARC 확인

  humansTxt:
    enabled: false  # 선택 사항, 팀 표시

  license:
    enabled: false  # 선택 사항, 오픈 소스 프로젝트용

# ID로 특정 검사 또는 서비스 무시
ignore:
  - sitemap
  - llms_txt
  - google_analytics

검사 및 서비스 무시

preflight ignore <id>를 사용하여 특정 검사 또는 서비스를 무음 처리하세요:

preflight ignore sitemap        # sitemap 검사 무시
preflight ignore sentry         # Sentry 서비스 검증 무시
preflight unignore sitemap      # sitemap 검사 다시 활성화
preflight checks                # 무시 가능한 모든 ID 나열

단일 비밀 결과 허용 목록

전체 secrets 검사를 무음 처리하는 것보다 개별 결과를 허용 목록에 추가하는 것이 좋습니다. 명령줄에서 일회성 예외를 추가하세요:

preflight ignore secrets web/js/golden-hour.js

그러면 preflight.yml의 checks.secrets.allowlist 아래에 경로 항목이 추가됩니다. path 필드는 프로젝트 상대 파일 경로를 기준으로 해석되는 doublestar 글로브(**는 디렉터리 간 매칭)입니다.

지문을 고정하세요. 경로 전용 허용 목록은 해당 파일에 향후 추가되는 모든 비밀을 조용히 수용합니다. 항목을 편집하고 fingerprint: "sha256:<hex>"를 추가하세요 — 감지된 비밀 값의 SHA-256입니다. 이제 키가 교체되거나 동일한 파일에 다른 비밀이 나타나면 preflight가 다시 경고합니다.

결과는 경로 + 지문으로 매칭되며, 전체 파일이 아닙니다. 파일의 허용 목록 지문은 동일한 파일의 다른 줄에 있는 다른 비밀을 억제하지 않습니다.

무시 가능한 검사 ID

SEO 및 소셜: seo_meta, canonical, structured_data, index_now (선택), og_twitter, viewport, lang

preflight v0.19.4