Agent skill
github-repo-governance
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/github-repo-governance
SKILL.md
GitHub Repository Governance
Overview
Repository governance covers policies, standards, and controls for managing GitHub repositories effectively. This skill includes repository settings, access controls, branch protection, security policies, and best practices for maintaining healthy and secure repositories.
When to use this skill: When setting up or managing governance policies for GitHub repositories.
Table of Contents
- Governance Framework
- Access Control
- Branch Protection
- Security Policies
- Repository Settings
- Governance Checklist
- Quick Reference
Governance Framework
Governance Levels
| Level | Scope | Controls |
|---|---|---|
| Organization | All repos | Policies, billing, members |
| Team | Team repos | Access, permissions |
| Repository | Single repo | Settings, protection, rules |
| Branch | Branch level | Protection, checks, restrictions |
Governance Principles
mermaid
graph TD
A[Security] --> B[Access Control]
A --> C[Branch Protection]
A --> D[Secrets Management]
E[Quality] --> F[Code Review]
E --> G[CI/CD Gates]
E --> H[Testing Requirements]
I[Compliance] --> J[Audit Logging]
I --> K[Policy Enforcement]
I --> L[Documentation Standards]
Governance Roles
| Role | Responsibilities | Permissions |
|---|---|---|
| Owner | Full control, billing, settings | Admin |
| Maintainer | Code review, merge, settings | Write |
| Contributor | Create PRs, issues | Write |
| Reader | View only | Read |
| Security Team | Security reviews, alerts | Admin |
| Compliance | Audit, policy enforcement | Read |
Access Control
Permission Levels
| Permission | Read | Write | Admin | Actions |
|---|---|---|---|---|
| Read | ✅ | ❌ | ❌ | View, clone |
| Triage | ✅ | ❌ | ❌ | + Manage issues, PRs |
| Write | ✅ | ✅ | ❌ | + Push branches |
| Maintain | ✅ | ✅ | ❌ | + Manage settings, teams |
| Admin | ✅ | ✅ | ✅ | + Full control |
Team-Based Access
yaml
# .github/teams.yml (organization level)
teams:
- name: backend-team
permission: admin
repositories:
- api-repo
- service-repo
- name: frontend-team
permission: write
repositories:
- web-repo
- mobile-repo
- name: security-team
permission: maintain
repositories:
- all # All repositories
CODEOWNERS File
# .github/CODEOWNERS
# Global owners
* @tech-lead @security-team
# Directory-specific owners
/api/ @api-team @backend-lead
/frontend/ @frontend-team @frontend-lead
/docs/ @documentation-team
# File pattern owners
*.md @documentation-team
*.sql @database-team
*.yml @devops-team
# Exclusions
.github/ @platform-team
External Collaborators
bash
# Add outside collaborator
gh api repos/:owner/:repo/collaborators/:username \
--permission write
# List collaborators
gh api repos/:owner/:repo/collaborators
# Remove collaborator
gh api \
--method DELETE \
-H "Accept: application/vnd.github.v3+json" \
/repos/:owner/:repo/collaborators/:username
Branch Protection
Protection Rules
yaml
# Branch protection settings (via GitHub UI or API)
# Main branch protection:
- Require pull request before merging
- Require approvals: 2 reviewers
- Dismiss stale reviews: 7 days
- Require review from CODEOWNERS
- Require status checks to pass
- Require branches to be up to date
- Restrict who can push: Team only
- Allow force pushes: No
- Require linear history: Yes
Required Status Checks
| Check Type | Purpose | Configuration |
|---|---|---|
| CI/CD | Build and deploy | GitHub Actions |
| Tests | Unit/integration tests | Test framework |
| Lint | Code quality | Linter tool |
| Security | Vulnerability scan | Security scanner |
| Coverage | Code coverage | Coverage tool |
| License | License compliance | License checker |
Protection Rule Examples
yaml
# .github/branch-protection.yml
protection_rules:
- pattern: main
required_approving_review_count: 2
required_status_checks:
- strict: true
contexts:
- ci/ci
- security/scan
enforce_admins: true
require_linear_history: true
allowed_push_users: []
- pattern: release/*
required_approving_review_count: 1
required_status_checks:
- strict: false
contexts:
- ci/ci
enforce_admins: false
Security Policies
Dependency Security
yaml
# .github/dependabot.yml
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
open-pull-requests-limit: 10
reviewers:
- "@security-team"
labels:
- "dependencies"
- "security"
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "monthly"
Secret Scanning
yaml
# .github/workflows/secret-scan.yml
name: Secret Scanning
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run secret scanner
uses: trufflesecurity/trufflehog-action@master
with:
path: ./
base: ${{ github.event.repository.default_branch }}
head: HEAD
Security Policies
markdown
# SECURITY.md
## Security Policy
### Supported Versions
We support the current major version and the previous major version for security updates.
### Reporting Vulnerabilities
Please report security vulnerabilities privately:
- Email: security@example.com
- PGP Key: [link to key]
### Response Time
- Critical: 24 hours
- High: 48 hours
- Medium: 1 week
- Low: 2 weeks
### Disclosure
We will disclose vulnerabilities after a fix is released.
Repository Settings
Visibility Settings
| Setting | Public | Private | Internal |
|---|---|---|---|
| Access | Anyone | Members only | Organization only |
| Forking | Enabled | Disabled | Disabled |
| Issues | Public | Private | Private |
| Wiki | Public | Private | Private |
| Pages | Public | Private | Private |
Feature Settings
yaml
# Repository features configuration
features:
issues: true
projects: true
wiki: true
discussions: false
actions: true
packages: true
pages: true
security_advisories: true
dependency_graph: true
vulnerability_alerts: true
code_scanning: true
secret_scanning: true
Issue Templates
markdown
# .github/ISSUE_TEMPLATE/bug_report.md
---
name: Bug report
about: Create a report to help us improve
title: '[BUG] '
labels: 'bug,needs-triage'
---
## Description
A clear description of the bug.
## Steps to Reproduce
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
## Expected Behavior
What you expected to happen.
## Actual Behavior
What actually happened.
## Environment
- OS: [e.g. Windows]
- Browser: [e.g. Chrome]
- Version: [e.g. 1.0.0]
Governance Checklist
Initial Setup
markdown
## Repository Setup Checklist
### Access Control
- [ ] Owners and maintainers configured
- [ ] Teams created and assigned
- [ ] CODEOWNERS file created
- [ ] External collaborators reviewed
- [ ] Permission levels documented
### Branch Protection
- [ ] Main branch protected
- [ ] Required reviewers set
- [ ] Status checks configured
- [ ] Force push disabled
- [ ] Linear history required
### Security
- [ ] Secret scanning enabled
- [ ] Dependabot configured
- [ ] Security policies documented
- [ ] Vulnerability alerts enabled
- [ ] Two-factor authentication required
### Features
- [ ] Issue templates created
- [ ] PR templates created
- [ ] Wiki enabled/disabled appropriately
- [ ] Projects enabled
- [ ] Discussions configured
Ongoing Governance
markdown
## Governance Review Checklist
### Access Review
- [ ] Review active collaborators
- [ ] Remove inactive users
- [ ] Update team memberships
- [ ] Audit access logs
- [ ] Review CODEOWNERS
### Policy Review
- [ ] Review branch protection rules
- [ ] Update security policies
- [ ] Review automation workflows
- [ ] Update templates
- [ ] Review governance docs
### Compliance Review
- [ ] Audit trail reviewed
- [ ] Security incidents logged
- [ ] Policy violations addressed
- [ ] Documentation updated
- [ ] Team training completed
Quick Reference
GitHub CLI Commands
bash
# Repository settings
gh repo edit --visibility private --enable-wiki
# List collaborators
gh repo collaborator list
# Add collaborator
gh repo collaborator add username --permission write
# Remove collaborator
gh repo collaborator remove username
# Create team
gh api orgs/:org/teams \
--method POST \
-f name=team-name \
-f privacy=closed \
-f permission=write
# Add team to repo
gh api \
--method PUT \
/orgs/:org/teams/:team/repos/:owner/:repo \
-f permission=maintain
Branch Protection Commands
bash
# View protection rules
gh api repos/:owner/:repo/branches/main/protection
# Set protection (requires API)
gh api \
--method PUT \
/repos/:owner/:repo/branches/main/protection \
-f required_pull_request_reviews=true \
-f required_approving_review_count=2
Governance Metrics
| Metric | Target | How to Track |
|---|---|---|
| Access review frequency | Quarterly | Regular access audits |
| Policy compliance | 100% | All repos follow policies |
| Security incidents | 0 per month | Monitor security alerts |
| Unauthorized access | 0 | Audit logs |
| Template usage | > 90% | Issues/PRs use templates |
Common Pitfalls
- Over-permissive access - Grant minimum necessary permissions
- No branch protection - Always protect main branches
- Ignoring security alerts - Respond to vulnerabilities promptly
- Outdated collaborators - Regularly review access
- No CODEOWNERS - Define code ownership clearly
- Missing templates - Use templates for consistency
- No audit trail - Track all governance actions
- Inconsistent policies - Standardize across organization
Additional Resources
Didn't find tool you were looking for?