shipit-skill — 개발자 도구 원패스 출시 파이프라인은(는) 무엇을 하나요?
기존 저장소를 "잘 동작하는 상태"에서 출시 + 등록 + 마케팅 가능한 상태로 전환합니다. 네 단계로 구성되며, 각 단계마다 명확한 종료 기준이 있습니다. 종료 기준이 이미 충족된 경우에만 해당 단계를 건너뛸 수 있습니다.
철학: 만들기 전에 먼저 살펴보십시오. 이미 존재하는 것과 생태계가 요구하는 것을 먼저 확인하십시오 — 사용자에게 바퀴를 재발명하지 말라고 조언하는 것과 같은 방식입니다.
0단계 — 정찰 (30초, 항상 수행)
무언가를 건드리기 전에 다음 검사를 실행하십시오:
- 기존 저장소 상태 —
git status,git remote -v, 최근git log. - 패키지 등록 여부 — 이름이 사용 중인가요? (
pip index versions <name>,npm view <name>, 레지스트리 CDN). 이름 충돌이 자주 발생하므로, npm의 경우 스코프 이름(@org/pkg)을 사용하면 오타 스쿼팅 규칙을 피할 수 있습니다. - 유사 프로젝트 — GitHub에서 직접적인 경쟁자를 검색하십시오. 존재한다면 차별점을 명시적으로 기록하고, 완전히 동일한 복제본을 만들지 마십시오.
- "종료 기준" 격차 — CI? Dockerfile? GitHub Release? Glama / awesome 디렉터리에 등록되어 있나요? 홍보 자료가 최신인가요? 누락된 항목의 체크리스트를 작성하십시오. 이 체크리스트가 나머지 작업을 주도합니다.
출력: 간단한 격차 보고서 + 계획. 격차가 큰 경우 1단계 전에 확인을 받으십시오.
1단계 — 엔지니어링 기준선
종료 기준: 기본 브랜치에서 CI 통과, 패키지 메타데이터 정확, Dockerfile 존재(MCP/CLI 서버인 경우).
- CI: GitHub Actions를 추가하십시오. Python: 지원되는 버전에 대한 매트릭스를 구성하지만, 최신 인터프리터가 필요한 추가 기능(예:
mcp>=2.0은 py3.10+ 필요 — 기본은 3.9에서 실행, 추가 기능은 3.12에서 실행)을 주의하십시오. 항상 린트 + 테스트 + 서버가 함께 제공되는 경우 컨테이너 MCP 핸드셰이크 작업을 포함하십시오. - Dockerfile: Glama 및 컨테이너 사용자에게 필요합니다. stdio MCP 서버의 경우: 기본 이미지 + 패키지 설치 +
CMD [서버-명령어]. 소스에서 빌드하십시오(COPY src). 게시된 패키지가 검증되지 않은 경우, 오래된 PyPI/npm 릴리스가 무음으로 인트로스펙션을 손상시킬 수 있습니다. .dockerignore: 이미지를 최소화하십시오(.git, 테스트, 홍보 자료, 문서 제외).- 메타데이터에서 버전 읽기: MCP
serverInfo.version과 CLI--version은 하드코딩된 문자열이 아닌 패키지 버전을 읽어야 합니다. - 의존성 하한선: 코드가 새 SDK API를 대상으로 하는 경우, 의존성 하한선을 설정하십시오(
mcp>=2.0).>=1.0으로 두지 마십시오. pip/npm이 최신 버전으로 해결하여 새 설치를 깨뜨릴 수 있습니다.
확인: 임시 가상 환경에서 pip install .[extras] / npm install이 깔끔하게 실행되는지 확인한 후, 컨테이너에 대해 MCP 핸드셰이크(initialize + tools/list)를 실행하십시오.
2단계 — 발행
종료 기준: 레지스트리에 패키지 등록, 태그와 노트가 포함된 GitHub Release, 깨끗한 환경에서 설치 확인 완료.
- 버전 범프 → 빌드 아티팩트 생성(
python -m build/npm pack). - 태그 + GitHub Release: 제목
vX.Y.Z, 노트에 변경 사항 / 설치 / 수정 사항 포함.gh release create를 사용하여 태그에서 첨부하십시오. - 레지스트리 발행:
- PyPI: 토큰 필요(세분화되어 패키지에 스코프 지정, 업로드 권한). 토큰 형식이 잘못되면 PyPI는
403 Invalid or non-existent authentication information을 반환합니다. UUID 스타일 문자열은 잘못된 것입니다. 실제 PyPI 토큰은pypi-로 시작합니다.twine upload에--username __token__을 사용하십시오. - npm: 스코프 이름을 사용하려면 조직이 존재해야 합니다. 자동화를 위해 2FA 우회 권한이 있는 세분화된 토큰을 사용하십시오.
--//registry.npmjs.org/:_authToken을 인라인으로 사용하면 자격 증명을 디스크에 쓰지 않습니다.
- PyPI: 토큰 필요(세분화되어 패키지에 스코프 지정, 업로드 권한). 토큰 형식이 잘못되면 PyPI는
- 새 설치 확인(필수): 가상 환경 / 깨끗한 디렉터리를 만들고 레지스트리에서 설치한 다음, 모듈 가져오기 / CLI 실행 / MCP 핸드셰이크를 수행하십시오. 이렇게 하면 "내 컴퓨터에서는 잘 되는데" 패키징 버그를 잡을 수 있습니다.
- 주의 사항:
- npm CDN은 첫 게시 후 몇 분 동안 캐시된 404를 제공합니다. 당황하지 말고 쿼리 매개변수로 캐시를 무효화하십시오.
- 재시도 시
File already exists오류는 일반적으로 첫 번째 시도가 성공했음을 의미합니다. - 잠금 파일 변동: 패키지 이름을 변경하면 항상
npm install을 실행하여 잠금 파일을 다시 생성해야 합니다. 그렇지 않으면 CI에서npm ci가 실패합니다.
3단계 — 디렉터리 등록
종료 기준: Glama에 점수 배지와 함께 등록 및 awesome PR 열림(또는 병합됨).
- Glama (
glama.ai/mcp/servers): 사용자가 브라우저를 통해 제출합니다(GitHub OAuth — 자동화 불가). 제출 전에 Dockerfile이 존재하고 인트로스펙션을 통과해야 합니다(1단계 참조). 제출 후 페이지가 나타나는 데 몇 분에서 몇 시간이 걸릴 수 있습니다.https://glama.ai/mcp/servers/<owner>/<repo>와/badges/score.svg를 폴링하십시오. 배지가 활성화되면 저장소 README에 추가하십시오:[](https://glama.ai/mcp/servers/owner/repo) - awesome-mcp-servers(및 유사한 큐레이션 목록): PR은 봇이 심사합니다. 목록의 현재 규칙(배지 + 언어 + 범위 + OS + 설치 명령어)에 따라 형식을 맞추십시오. 유지 관리자는 이제 항목에 Glama 배지를 요구합니다. Glama를 먼저 제출하십시오. PR 제목에
🤖🤖🤖를 추가하여 에이전트 고속 트랙에 옵트인하십시오. 포크 → 최신 업스트림 main에서 브랜치 생성 → 항목 추가 → PR. 이전 PR이 비활동으로 종료된 경우, 브랜치를 강제 푸시하거나 다시 생성하십시오. - 기타 디렉터리(Smithery, PulseMCP, mcp.so 등): Smithery는 저장소 루트에 있는
smithery.yaml을 읽습니다(stdio 시작 명령어 + 선택적 환경 스키마).
4단계 — 홍보 자료
종료 기준: 홍보 문서의 버전/링크/PR 번호가 실제와 일치하고, 플랫폼별 게시물이 붙여넣기 준비가 되어 있어야 합니다(사용자가 수동으로 게시 — 가짜 자동화 금지).
promo/디렉터리에 플랫폼별 파일(V2EX, 知乎, Reddit, X, 커뮤니티)을 유지 관리하십시오.- 최신 상태 확인(버전/PR이 변경될 때마다 실행): 프로모 파일에서 오래된 버전 번호, 끊긴 PR 링크, 오래된 릴리스 URL을 검색하십시오. 업데이트하거나 오래된 것으로 표시하십시오.
- 사실 규율: 게시하기 전에 모든 숫자/주장을 확인하십시오. 도구를 다시 실행하고 출력을 비교하십시오. 잘못된 주장은 댓글에서 까발려집니다(예: 실제로는 GitHub 메타데이터 결함인 "LICENSE 없음" 주장).
- 설치 명령어는 고정하지 않고 유지하십시오(
pip install pkg). 홍보 자료가 썩지 않도록 합니다.
CLI 빠른 참조 (shipit-skill)
다음 명령어를 실행하여 저장소를 단계별로 진행하십시오. 모든 명령어는 기본적으로 출력만 합니다; 부수 효과가 있는 변형은 --execute를 통해 옵트인해야 합니다.
| 명령어 | 기능 | 자동 / 출력 |
|---|---|---|
doctor [--json] | 환경 자체 점검: gh 인증, 토큰 설정, main에서 깨끗한 트리 | 출력; 격차가 있으면 1로 종료 |
preflight [--dir .] [--version X.Y.Z] [--json] | 출시 준비 격차 보고서 | 출력 |
init <dir> --server <srv> --pkg <pkg> [--force] [--dry-run] | CI/Dockerfile/smithery.yaml/promo 스캐폴딩 | 파일 쓰기 |
ci --lang python [--server srv] [--write path] [--release] | ci.yml 생성; --release는 release.yml 생성 | 출력 / 쓰기 |
| `bump patch | minor | major |
release --lang python --pkg <pkg> [--repo o/r] [--execute] | doctor 게이트 → 범프→빌드→발행→태그→gh 릴리스→프로모 확인. 태그/릴리스는 발행 성공 후에만 생성됨; 발행 실패는 커밋을 롤백; 재실행 시 기존 태그/릴리스 건너뜀; 노트는 CHANGELOG에서 가져옴 | 출력 / 실행 |
publish --lang python --pkg <pkg> [--server srv] [--execute] | 레지스트리 업로드(PYPI_TOKEN/NPM_TOKEN 환경 변수에서 토큰 읽음) + 새 설치 확인 | 출력 / 실행 |
check-promo --dir promo --version X.Y.Z [--prs id=state,...] [--no-links] [--report] [--fix] | 오래된 버전 / 알 수 없는 PR / 깨진 링크 확인; --report는 JSON 출력; --fix는 오래된 버전을 다시 쓰고 알 수 없는 PR 표시 | 출력 / JSON / 수정 |
check-glama --repo o/r [--poll N] [--add-badge] [--json] | Glama 등록 대기; --add-badge는 활성화되면 README 배지 작성; --json 구조화된 출력 | 출력 / 쓰기 |
awesome-pr --upstream o/r --repo o/r --fork o/r --branch b [--execute --category C --description D --install I] | PR 레시피, 또는 실제로 포크→편집→푸시→gh pr create 실행 | 출력 / 실행 |
토큰: 디스크에 저장되지 않습니다. publish/release --execute는 환경 변수에서 PYPI_TOKEN 또는 NPM_TOKEN을 읽습니다. 사용자에게 토큰을 요청하고 인라인으로 전달하십시오.
자동화 경계
| 단계 | 실행 주체 |
|---|---|
| CI 파일, Dockerfile, 메타데이터, 코드 수정 | 에이전트 |
| 빌드 아티팩트, 새 설치 확인 | 에이전트 |
| 레지스트리 발행(PyPI/npm) | 에이전트, 사용자가 제공한 토큰 사용 |
| Glama 브라우저 제출 | 사용자(OAuth) |
| awesome/기타 PR 생성 | 에이전트 |
| 플랫폼에 게시 | 사용자 |
자격 증명을 절대 위조하지 마십시오. 토큰을 명시적으로 요청하고 인라인으로 사용하며, 절대 파일에 쓰지 마십시오.
실전 교훈 (wheel-hub + zspace-cli 출시 경험에서)
mcp>=1.0을 추가 기능에 설정하고 새 SDK를 사용하면 새 설치가 충돌합니다. 하한선을 설정하십시오.- Python 3.9는
mcp>=2.0을 설치할 수 없습니다. CI 매트릭스는 기본과 추가 기능을 분리해야 합니다. - YAML 블록 스칼라 + 인라인 python heredoc = 워크플로우 손상. 스크립트 파일을 사용하십시오.
- MCP 2.x
Server객체에는list_tools가 없습니다.@server.tool()데코레이터를 사용하십시오. - Glama 인트로스펙션은 스모크 테스트에서 stdin을 잠시 열어 두어야 합니다(
sleep 1). - PyPI 토큰 형식:
pypi-...가 실제 토큰이고, UUID는 잘못된 것입니다. - npm 오타 스쿼팅은
wheel-hub를wheelhub옆에 차단합니다. 스코프 이름이 작동합니다. .dockerignore가 누락되면 거대한 이미지 / 빌드 컨텍스트에 비밀 정보가 포함됩니다.
이 스킬은 실제 출시 파이프라인에서 추출되었으며, wheel-hub, zspace-cli, media-manager-skill 출시 경험을 바탕으로 합니다.