---
name: github-repo-governance-audit
description: >
  Use this skill when the user asks to audit a GitHub repository, check
  repository health, review project governance quality, check if a project
  has the required files like LICENSE/README/CONTRIBUTING/SECURITY, review
  GitHub project governance practices, check OpenSSF Scorecard, assess
  repository compliance with open source best practices, or wants to know
  how well-governed a GitHub project is. Also trigger for 저장소 거버넌스 점검,
  공개SW 저장소 감사, 저장소 품질 평가, GitHub 저장소 점검, 오픈소스 프로젝트 감사,
  공개SW R&D 저장소 점검. Keywords: repository audit, governance audit, repo health,
  OpenSSF scorecard, branch protection, Dependabot, CI/CD check, 저장소 감사.
---

# GitHub 저장소 거버넌스 감사 스킬
# GitHub Repository Governance Audit Skill

## 개요 / Overview

이 스킬은 GitHub 저장소의 거버넌스 품질을 종합적으로 점검하고 0–100점의
스코어를 산출합니다. 공개SW R&D 과제 저장소 점검 기준과 OpenSSF Scorecard
방법론을 결합하여 한국 공공기관 환경에 최적화된 감사를 수행합니다.

---

## 입력 / Input

| 파라미터 | 필수 여부 | 설명 |
|---------|---------|------|
| `github_url` | 필수 | GitHub 저장소 URL |
| `context` | 선택 | `r&d` (공개SW R&D) \| `enterprise` \| `general` (기본값) |
| `output_dir` | 선택 | 출력 디렉토리 (기본값: `./governance-output/`) |

---

## 점검 항목 및 배점 / Check Items & Scoring

총 100점 만점으로 구성됩니다.

### 카테고리 1: 필수 파일 (30점)

| 항목 | 배점 | 점검 기준 |
|------|------|---------|
| LICENSE 파일 | 10점 | 존재(5점) + SPDX 식별자 사용(3점) + OSI 승인 라이선스(2점) |
| README.md | 10점 | 존재(3점) + 설치 방법(2점) + 사용법(2점) + 기여 안내(1점) + 배지(1점) + 라이선스 고지(1점) |
| CONTRIBUTING.md | 5점 | 존재(3점) + PR 절차 포함(2점) |
| CODE_OF_CONDUCT.md | 3점 | 존재(2점) + Contributor Covenant 또는 동등 기준(1점) |
| SECURITY.md | 2점 | 존재(1점) + 취약점 신고 절차 포함(1점) |

### 카테고리 2: 이슈·PR 관리 (20점)

| 항목 | 배점 | 점검 기준 |
|------|------|---------|
| Issue 템플릿 | 5점 | `.github/ISSUE_TEMPLATE/` 존재(3점) + 버그/기능요청 구분(2점) |
| PR 템플릿 | 5점 | `.github/PULL_REQUEST_TEMPLATE.md` 존재(3점) + 체크리스트 포함(2점) |
| 이슈 반응성 | 5점 | 평균 첫 응답 시간 < 14일(5점), < 30일(3점), < 60일(1점) |
| PR 머지 상태 | 5점 | Open PR 수 및 오래된 PR 비율 평가 |

### 카테고리 3: 브랜치 및 보안 (25점)

| 항목 | 배점 | 점검 기준 |
|------|------|---------|
| 기본 브랜치 보호 | 8점 | PR 필수(3점) + 리뷰 필수(3점) + 강제 push 차단(2점) |
| Dependabot 보안 알림 | 7점 | 활성화(4점) + 자동 PR(3점) |
| 보안 취약점 알림 | 5점 | GitHub Security Alerts 활성화 |
| 코드 스캔 (CodeQL 등) | 5점 | GitHub Actions 코드 스캔 존재 |

### 카테고리 4: CI/CD 및 자동화 (15점)

| 항목 | 배점 | 점검 기준 |
|------|------|---------|
| GitHub Actions | 8점 | CI 워크플로 존재(4점) + 테스트 실행(2점) + 빌드 성공(2점) |
| 릴리스 및 버전 관리 | 4점 | 릴리스 태그 존재(2점) + SemVer 준수(2점) |
| 자동화 배지 | 3점 | CI 상태 배지(1점) + 커버리지 배지(1점) + 품질 배지(1점) |

### 카테고리 5: 커뮤니티 및 지속가능성 (10점)

| 항목 | 배점 | 점검 기준 |
|------|------|---------|
| 최근 활동성 | 5점 | 최근 90일 내 커밋(5점), 180일(3점), 365일(1점) |
| 기여자 다양성 | 3점 | 기여자 수 5명 이상(3점), 2명 이상(1점) |
| 문서 품질 | 2점 | Wiki 또는 docs/ 디렉토리(2점) |

---

## 작업 절차 / Workflow

### 1단계: 저장소 기본 정보 수집

```bash
# 저장소 메타데이터 수집
gh repo view {owner}/{repo} --json \
  name,description,defaultBranchRef,primaryLanguage,languages,\
  licenseInfo,isPrivate,stargazerCount,forkCount,watchers,\
  pushedAt,createdAt,updatedAt,hasIssuesEnabled,hasWikiEnabled,\
  isArchived,isDisabled,visibility

# 기여자 수 확인
gh api repos/{owner}/{repo}/contributors --paginate | jq 'length'

# 최근 커밋 활동
gh api repos/{owner}/{repo}/commits \
  --jq '[.[] | .commit.author.date] | first'
```

### 2단계: 필수 파일 점검

```bash
# 루트 파일 목록 확인
gh api repos/{owner}/{repo}/contents/ \
  --jq '[.[] | .name] | sort'

# LICENSE 파일 확인
gh api repos/{owner}/{repo}/license \
  --jq '{name: .license.name, spdx_id: .license.spdx_id}'

# CONTRIBUTING.md 확인
gh api repos/{owner}/{repo}/contents/CONTRIBUTING.md 2>/dev/null && \
  echo "CONTRIBUTING.md: 존재" || echo "CONTRIBUTING.md: 없음"

# CODE_OF_CONDUCT.md
gh api repos/{owner}/{repo}/contents/CODE_OF_CONDUCT.md 2>/dev/null

# SECURITY.md
gh api repos/{owner}/{repo}/contents/SECURITY.md 2>/dev/null

# .github 디렉토리 내용 확인
gh api repos/{owner}/{repo}/contents/.github 2>/dev/null | \
  jq '[.[] | .name]'

# 이슈/PR 템플릿
gh api repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE 2>/dev/null
gh api repos/{owner}/{repo}/contents/.github/PULL_REQUEST_TEMPLATE.md 2>/dev/null
```

### 3단계: README 품질 분석

```bash
# README 내용 다운로드
gh api repos/{owner}/{repo}/readme \
  --jq '.content' | base64 -d > /tmp/README.md

# 품질 항목 체크 (주요 키워드 존재 여부)
# 설치 방법: "install", "설치", "## Getting Started"
# 사용법: "usage", "사용법", "example", "예시"
# 기여 안내: "contributing", "기여", "CONTRIBUTING"
# 라이선스 고지: "license", "라이선스", "licensed under"
# 배지: "shields.io", "badge", "img.shields"
grep -i "install\|설치\|getting started" /tmp/README.md
grep -i "usage\|사용법\|example\|예시" /tmp/README.md
grep -i "contributing\|기여" /tmp/README.md
grep -i "license\|라이선스" /tmp/README.md
grep -i "shields.io\|badge" /tmp/README.md
```

### 4단계: 브랜치 보호 및 보안 설정 점검

```bash
# 기본 브랜치 보호 규칙 확인 (권한 필요)
gh api repos/{owner}/{repo}/branches/{default_branch}/protection 2>/dev/null

# Dependabot 설정 파일 확인
gh api repos/{owner}/{repo}/contents/.github/dependabot.yml 2>/dev/null

# GitHub Actions 워크플로 목록
gh api repos/{owner}/{repo}/actions/workflows \
  --jq '[.workflows[] | {name: .name, state: .state, path: .path}]'

# 보안 취약점 알림 상태
gh api repos/{owner}/{repo}/vulnerability-alerts 2>/dev/null && \
  echo "Security Alerts: 활성화" || echo "Security Alerts: 비활성화 또는 확인 불가"
```

### 5단계: 릴리스 및 버전 관리 점검

```bash
# 최신 릴리스 정보
gh release list --repo {owner}/{repo} --limit 5

# 태그 목록
gh api repos/{owner}/{repo}/tags \
  --jq '[.[] | .name] | first(5)'

# SemVer 패턴 확인 (v1.2.3 또는 1.2.3)
gh api repos/{owner}/{repo}/tags --jq \
  '[.[] | .name | select(test("^v?[0-9]+\\.[0-9]+\\.[0-9]+"))] | length'
```

### 6단계: OpenSSF Scorecard 연동 (선택)

OpenSSF Scorecard API를 통해 보안 점수를 가져옵니다:

```bash
# OpenSSF Scorecard API (공개 저장소)
curl -s "https://api.securityscorecards.dev/projects/github.com/{owner}/{repo}" \
  | jq '{score: .score, checks: [.checks[] | {name: .name, score: .score}]}'
```

또는 로컬 scorecard CLI 사용:

```bash
# Scorecard CLI 설치
brew install scorecard

# 실행
scorecard --repo=github.com/{owner}/{repo} \
  --checks=Branch-Protection,CI-Tests,Code-Review,Dependency-Update-Tool,\
  License,Maintained,Packaging,Pinned-Dependencies,SAST,Signed-Releases,\
  Token-Permissions,Vulnerabilities
```

### 7단계: 점수 계산 및 보고서 생성

각 항목의 점수를 집계하여 총점과 등급을 산출합니다:

| 점수 | 등급 | 설명 |
|------|------|------|
| 90–100 | A+ | 우수 — 공개SW R&D 우수 사례 수준 |
| 80–89 | A | 양호 — 대부분의 거버넌스 요건 충족 |
| 70–79 | B | 보통 — 일부 개선 필요 |
| 60–69 | C | 미흡 — 다수 항목 개선 필요 |
| 0–59 | D | 불량 — 즉시 개선 필요 |

---

## 출력 파일 / Output Files

| 파일 | 설명 |
|------|------|
| `repo-governance-audit.md` | 종합 감사 보고서 (점수, 항목별 결과, 권고사항) |
| `governance-checklist.json` | 항목별 점수 데이터 (자동화 연동용) |

### repo-governance-audit.md 구조

```markdown
# 저장소 거버넌스 감사 보고서
## {repo_name} — {audit_date}

### 종합 점수: {score}/100 (등급: {grade})

### 카테고리별 점수
| 카테고리 | 획득점수 | 만점 | 달성률 |
|---------|--------|------|-------|
| 필수 파일 | X | 30 | XX% |
...

### 항목별 상세 결과
[항목별 Pass/Fail/Partial 및 이유]

### 주요 발견사항
[Good: 잘 되고 있는 항목]
[Warning: 개선이 필요한 항목]
[Critical: 즉시 조치가 필요한 항목]

### 개선 권고사항 (우선순위별)
1. [즉시 조치] ...
2. [단기 개선] ...
3. [중장기 계획] ...

### OpenSSF Scorecard 결과 (해당 시)
```

---

## 도구 의존성 / Tool Dependencies

| 도구 | 용도 | 설치 |
|------|------|------|
| `gh` | GitHub API 접근 | `brew install gh` |
| `jq` | JSON 처리 | `brew install jq` |
| `scorecard` | OpenSSF Scorecard (선택) | `brew install scorecard` |
| `curl` | OpenSSF Scorecard API | 시스템 기본 |

---

## 한국 공공기관 컨텍스트 / Korean Public Sector Context

**공개SW R&D 과제 저장소 점검 기준 (NIA):**

공개SW 연구개발 과제의 GitHub 저장소는 다음 요건을 충족해야 합니다:

1. **필수 제출 파일**: LICENSE, README, CONTRIBUTING 파일 포함
2. **라이선스**: 명확한 OSI 승인 오픈소스 라이선스 사용
3. **소스코드 공개**: 개발 과정 중 지속적 커밋 (최종 일괄 제출 불가)
4. **릴리스 관리**: 마일스톤별 태그·릴리스 생성
5. **문서화**: 설치·실행 가이드, API 문서 등

이 스킬의 점검 항목은 위 요건과 직접 매핑됩니다.

---

## 사용 예시 / Usage Examples

```
"https://github.com/example/project 저장소의 거버넌스 상태를 점검해줘"

"공개SW R&D 과제 기준으로 이 저장소가 요건을 충족하는지 감사해줘:
https://github.com/nia-project/open-source-tool"

"이 저장소의 OpenSSF Scorecard 점수와 거버넌스 점수를 함께 산출해줘"
```

---

## 참조 / References

- [OpenSSF Scorecard](https://github.com/ossf/scorecard)
- [GitHub Repository Best Practices](https://docs.github.com/en/repositories)
- [공개SW R&D 저장소 운영 가이드라인 (NIA)](https://www.oss.kr)
- [Repolinter — GitHub Policy](https://github.com/todogroup/repolinter)
- [CHAOSS Metrics for Community Health](https://chaoss.community/metrics/)