저장소 오픈소스화
외부인이 사전 정보 없이도 저장소를 빌드, 사용 및 기여할 수 있도록 공개 릴리스를 준비하고, 민감한 정보가 함께 배포되지 않도록 합니다. 단계를 순서대로 진행하십시오. 시크릿(secret) 감사가 먼저 오는 이유는 그 결과(저장소 유지 vs. 재생성)가 이후 모든 작업에 영향을 미치기 때문입니다.
사용 시기
- 비공개 저장소를 공개로 전환할 때
- 기존 공개 저장소의 릴리스 품질을 감사할 때("공식화")
- 프로젝트 라이선스를 선택할 때
- 공개 출시에 앞서 패키징, 버전 관리 또는 릴리스 자동화를 설정할 때
사용하지 말아야 할 시기
- 이미 릴리스된 프로젝트의 일상적인 개발(릴리스 이벤트가 없음)
- 타사 코드의 취약점 감사(보안 검토 스킬 사용)
- 비공개로 유지될 저장소에서 패키지를 게시하는 경우 — 릴리스 관리 단계만 적용되고 나머지는 건너뜁니다.
워크플로우
1단계: 조직 프로필 감지
bash {baseDir}/scripts/detect_org.sh
이 스크립트는 git 리모트와 최근 커미터 이메일을 검사하여 프로필 이름을 출력합니다. trailofbits가 출력되면 지금 references/trailofbits.md를 읽고 나머지 단계 전체에 걸쳐 해당 라이선스 정책, 게시 계정 및 프로세스 노트를 적용하십시오. generic이 출력되면 일반적인 지침만 따르십시오. 사용자가 감지가 잘못되었다고 말하면 사용자를 신뢰하십시오.
2단계: 시크릿 감사 — 다른 모든 것보다 먼저
한 번이라도 시크릿(API 키, 자격 증명, 클라이언트 데이터)을 포함한 적이 있는 저장소는 공개로 전환해서는 안 됩니다. 기록 재작성은 오류가 발생하기 쉽고 포크, 캐시 또는 CI 아티팩트에 도달하지 않습니다. 신뢰할 수 있는 해결책은 새 저장소를 만드는 것입니다. 현재 트리를 복사하고 커밋한 다음, 이전 저장소는 비공개로 보관합니다.
- 프로젝트가 시크릿이나 클라이언트 기밀 자료를 처리한 적이 있는지 질문하십시오. 보안 컨설팅 도구의 경우 테스트 픽스처나 예제 데이터가 클라이언트 작업에서 비롯되었는지도 질문하십시오.
- 가능하면 전용 도구를 사용하여 전체 기록을 스캔하십시오 —
gitleaks git .또는trufflehog git file://.— 눈으로 확인하는 것보다 낫습니다. - git 트리 너머도 확인하십시오: GitHub Actions 로그 및 아티팩트, 이전 릴리스, 이슈 및 PR 기록, 저장소 위키 모두 저장소와 함께 공개됩니다.
- 공개 전환 후, 저장소 설정에서 GitHub 시크릿 스캐닝 및 푸시 보호를 활성화하십시오.
다음 변명은 거부하십시오 — 이 단계는 게시 후에 수정할 수 없는 유일한 단계입니다.
- "키가 취소되었으므로 기록은 괜찮습니다." 취소된 자격 증명은 여전히 인프라 이름, 내부 URL 및 공격자가 표적으로 삼는 패턴을 유출합니다.
- "git-filter-repo로 기록을 다시 작성하겠습니다." 다시 작성은 포크, 클론, 캐시 및 CI 아티팩트를 놓칩니다. 새 저장소 접근 방식은 그렇지 않습니다.
- "단지 테스트 데이터일 뿐입니다." 클라이언트 작업이나 프로덕션 시스템에서 파생된 픽스처는 레이블에 관계없이 기밀입니다.
3단계: 준비 상태 확인 실행
bash {baseDir}/scripts/check_readiness.sh
이 스크립트는 존재 여부를 나타내는 체크리스트(README, LICENSE, CONTRIBUTING, SECURITY.md, CI, 테스트, semver 태그 등)를 출력하고 일반적으로 시크릿을 포함하는 추적 파일에 대해 경고합니다. 체크되지 않은 항목은 하드 실패가 아닌 논의 프롬프트로 취급하십시오 — 연구 프로토타입은 주력 라이브러리와 동일한 모든 것이 필요하지 않습니다. 사용자와 함께 격차를 검토하고 이 프로젝트에 중요한 부분을 수정하십시오.
4단계: 문서화
README는 프로젝트의 정문입니다. 다음을 설명하는지 확인하십시오.
- 프로젝트가 무엇인지와 해결하는 문제(첫 번째 단락)
- 설치 방법 — 패키지 관리자, 컨테이너 이미지 또는 소스에서 빌드; 새로운 클론 빌드는 저장소에 있는 것만 사용하여 작동해야 합니다.
- 사용 방법 — 최소한 하나의 구체적이고 복사-붙여넣기 가능한 예제
- 기여 방법 — 인라인 또는
CONTRIBUTING.md를 통해 - 라이선스 — 이름을 명시하는 짧은 섹션
또한 다음을 추가하십시오.
SECURITY.md— 취약점 보고 지침(연락처 주소 또는 GitHub 비공개 취약점 보고). 보안 도구의 경우 기본 요구사항입니다.- API 문서, 빌드 및 호스팅(GitHub Pages via CI가 일반적인 경로), README와 저장소 웹사이트 필드에서 연결됩니다. 생태계별 문서 도구는 아래 언어 참조를 참조하십시오.
- 프로젝트가 외부 기여자를 기대하는 경우 행동 강령.
5단계: 라이선스
라이선스가 없으면 가시성과 관계없이 오픈 소스가 아닙니다. 선택 기준과 메커니즘은 references/licensing.md를 읽으십시오. 간단히 말하면:
- 1단계에서 감지된 경우 조직의 정책을 적용합니다.
- 그렇지 않은 경우: 허용적 기본값으로 Apache 2.0, 경쟁업체의 개인적 수정이 실제로 우려되는 경우 AGPLv3, 코드가 아닌 아티팩트의 경우 Creative Commons.
LICENSE파일을 추가하고, 패키지 메타데이터에 SPDX 식별자를 설정하고, README에 라이선스를 명시한 다음 세 가지가 모두 일치하는지 확인합니다.
6단계: 테스트 및 CI
- 테스트 스위트가 존재하고 통과하는지 확인하십시오. 실패하는 기본 브랜치가 있는 공개 저장소는 포기를 나타냅니다.
- CI가 모든 PR에서 지원되는 언어 버전 및 플랫폼 매트릭스 전반에 걸쳐 테스트를 실행하는지 확인하십시오.
- CI에서 포맷팅 및 린팅을 적용하여(아래 참조의 언어별 도구) 스타일 논쟁이 리뷰에 도달하지 않도록 하십시오.
- 기존 도구를 존중하십시오. 오픈소스화의 일부로 작동하는 포맷터, 린터 또는 타입 검사기를 교체하지 마십시오. 현재 세대보다 뒤처진 경우(언어 참조에서 현재 도구를 명명함) 관리자에게 경고하고 결정을 맡기십시오. 카테고리가 완전히 누락된 경우(타입 검사기 없음, 포맷터 없음)에만 현재 기본값을 추가하십시오.
- CI가 커버리지 하락 시 실패하도록 커버리지 게이트를 고려하십시오.
- 워크플로우 자체가 공격 표면이 되기 전에 강화하십시오.
- 타사 액션을 전체 커밋 SHA에 고정하고,
github-actions에 대해 Dependabot을 활성화하여 핀을 최신 상태로 유지하십시오. - 최소 권한
permissions:블록을 설정하십시오(permissions: {}에서 시작). zizmor .github/workflows/로 감사하고actionlint로 린트하십시오.
- 타사 액션을 전체 커밋 SHA에 고정하고,
7단계: 저장소 설정
- 기본 브랜치에 대한 브랜치 보호: 강제 푸시 금지, PR 필수. 새 저장소에는 규칙 세트를 선호합니다. 클래식 브랜치 보호는 계속 지원됩니다.
- 병합 보호: 필수 상태 확인으로 PR이 실패하는 테스트와 병합되지 않도록 합니다.
- Dependabot 또는 Renovate를 종속성 및 Actions 업데이트에 사용합니다. 업데이트를 그룹화하여 PR 노이즈를 줄이고, 새로 게시되고 때때로 하이재킹된 버전이 적용되기 전에 숙성되도록 쿨다운 기간(예: 7일)을 설정합니다.
- **
.editorconfig**를 사용하여 기여자의 편집기가 공백 기본 설정에 동의하도록 합니다. - 레이블: 하나 이상의 이슈 또는 PR에 필요할 때 즉시 생성합니다. 측면(패싯)에 대한 접두사가 잘 확장됩니다(
C:컴포넌트,P:플랫폼). 작업 예제는 blight의 레이블을 참조하십시오.
8단계: 릴리스 및 버전 관리
- 모든 릴리스에
vX.Y.Z태그를 지정하고 semver를 따릅니다. 릴리스 후보 및 사전 릴리스에는-rc.N/-pre.N접미사를 사용합니다. - 릴리스를 CI 기반으로 만듭니다: 태그 푸시(또는 GitHub 릴리스 게시)가 수동 단계 없이 빌드, 패키징 및 업로드를 트리거합니다. 릴리스는
git tag vX.Y.Z && git push origin vX.Y.Z여야 합니다. - 개인 계정이 아닌 조직 소유 계정으로 패키지를 게시하고, 인덱스가 지원하는 곳에서는 장기 토큰 대신 신뢰할 수 있는 게시(trusted publishing, OIDC)를 사용합니다.
9단계: 언어별 관행
마커 파일에서 프로젝트의 언어를 식별하고 패키징, 게시 및 품질 도구에 대한 일치하는 참조를 읽으십시오.
| 마커 파일 | 참조 |
|---|---|
pyproject.toml, setup.py | references/python.md — 도구는 현대 파이썬 스킬에 위임합니다 |
CMakeLists.txt, Makefile (C/C++) | references/c-cpp.md |
Cargo.toml | references/rust.md |
go.mod | references/go.md |
package.json | references/javascript.md |
Gemfile, *.gemspec | references/ruby.md |
다른 생태계의 경우 교차 적용 원칙을 적용하십시오: 새로운 클론에서 재현 가능한 빌드, CI 기반 릴리스, 신뢰할 수 있는 게시 또는 조직 소유 계정, 패키지 매니페스트의 라이선스 메타데이터.
최종 검토
가시성 전환 전에 외부인의 관점에서 확인하십시오.
- 깨끗한 디렉토리에 클론하고 README의 빌드 지침을 그대로 따르십시오 — 암묵적 지식 없이 작동합니까?
{baseDir}/scripts/check_readiness.sh를 다시 실행하고 남은 격차가 의도적인 선택이며 사용자에게 명시되었는지 확인하십시오.- 시크릿 감사(2단계)가 실제로 수행되었는지 확인하십시오. 이 단계는 게시 후에 수정할 수 없는 유일한 단계입니다.
저장소를 공개로 만드는 것은 저장소 설정 변경입니다. 조직에 관련 프로세스가 있는 경우 릴리스와 발표를 함께 진행하십시오.
추가 리소스
참조 파일
- references/licensing.md — 라이선스 선택 기준, SPDX 메타데이터, 포크 및 재라이선싱
- references/trailofbits.md — Trail of Bits 정책 오버레이(1단계에서 감지된 경우에만 로드됨)
- references/python.md, references/c-cpp.md, references/rust.md, references/go.md, references/javascript.md, references/ruby.md — 언어별 패키징, 게시 및 품질 도구
스크립트
scripts/detect_org.sh— git 리모트 및 커미터 이메일에서 조직 프로필(trailofbits또는generic)을 출력합니다.scripts/check_readiness.sh— 릴리스 준비 파일의 존재 여부를 나타내는 표시를 출력하고 일반적으로 시크릿을 보유하는 추적 파일에 플래그를 지정합니다.