Github Repo Governance

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

1. Governance Framework
2. Access Control
3. Branch Protection
4. Security Policies
5. Repository Settings
6. Governance Checklist
7. Quick Reference

Governance Framework

Governance Levels

Governance Principles

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

Access Control

Permission Levels

Team-Based Access

# .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

# 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

# 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

Protection Rule Examples

# .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

# .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

# .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

# 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

Feature Settings

# 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

# .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

## 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

## 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

# 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

# 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

Common Pitfalls

1. Over-permissive access - Grant minimum necessary permissions
2. No branch protection - Always protect main branches
3. Ignoring security alerts - Respond to vulnerabilities promptly
4. Outdated collaborators - Regularly review access
5. No CODEOWNERS - Define code ownership clearly
6. Missing templates - Use templates for consistency
7. No audit trail - Track all governance actions
8. Inconsistent policies - Standardize across organization

Additional Resources

• GitHub Repository Settings
• Branch Protection
• Managing Teams
• CODEOWNERS Documentation