🗳️ GitForge Governance Guide

Enterprise-Grade Governance with Weighted Voting and Complete Audit Trails

📋 Table of Contents

Overview
Governance Model
Weighted Voting System
Governance Audit Log
Configuration Guide
Best Practices
Troubleshooting

🎯 Overview

GitForge Governance provides enterprise-grade control over critical decisions through a transparent, auditable weighted voting system. Every vote, merge, veto, and policy change is recorded in an immutable audit log.

Key Principles

Transparency: Every decision is recorded and auditable
Accountability: All actions tied to specific actors with timestamps
Security: Cryptographically hashed audit trail prevents tampering
Compliance: 7-year retention meets regulatory requirements
Flexibility: Customizable roles, weights, and thresholds

🏛️ Governance Model

Role-Based Hierarchy

GitForge uses a role-based governance model where each role has specific permissions and voting power:

Role	Vote Weight	Can Merge	Can Override	Can Veto	Permissions
Founder	100	✅ Yes	✅ Yes	✅ Yes	Full control
Lead Maintainer	75	✅ Yes	❌ No	✅ Yes	Senior decisions
Maintainer	50	✅ Yes	❌ No	❌ No	Standard decisions
Reviewer	25	❌ No	❌ No	❌ No	Code review only
Contributor	10	❌ No	❌ No	❌ No	Voting only

How Voting Works

PR Created: Developer submits pull request
Voting Begins: Maintainers review and vote
Score Calculated: Weighted votes are summed
Threshold Check: Does approval percentage meet threshold?
Veto Check: Has anyone vetoed?
Merge Decision: PR is merged or blocked

Voting Thresholds

Different PR types require different approval thresholds:

PR Type	Threshold	Special Rules
Normal	50%	Standard approval
Bounty	60%	Requires additional review
Security	75%	Requires founder approval
Governance	80%	Requires founder approval

🗳️ Weighted Voting System

Understanding Vote Weights

Vote weights determine how much influence each maintainer's vote has on the final decision:

Example: PR with 3 votes

Founder votes "approve" (weight: 100)
Lead Maintainer votes "approve" (weight: 75)
Reviewer votes "request changes" (weight: 25)

Total weight: 100 + 75 + 25 = 200
Approve weight: 100 + 75 = 175
Approval percentage: 175 / 200 = 87.5%

Result: APPROVED (exceeds 50% threshold)

Vote Types

Each maintainer can cast one of four vote types:

Approve - Supports the PR
Request Changes - Opposes the PR
Abstain - Neutral, doesn't count toward approval
Veto - Blocks the PR regardless of other votes

Veto Power

A veto vote immediately blocks a PR from merging:

Founder votes "approve" (weight: 100)
Lead Maintainer votes "veto" (weight: 75)

Result: BLOCKED (veto overrides approval)

Who Can Veto:

Founder
Lead Maintainers
(Configurable in GOVERNANCE_CONFIG.json)

When to Use Veto:

Security vulnerabilities
Architectural violations
Policy breaches
Critical bugs

Override Capability

Only the Founder can override a blocked PR:

PR is blocked due to insufficient votes
Founder executes override with reason: "Critical hotfix"

Result: PR MERGED (override recorded in audit log)

Important: Overrides are logged and auditable. Use sparingly.

📋 Governance Audit Log

What Gets Logged

The governance audit log (github/GOVERNANCE_AUDIT.json) records:

Votes Cast
- Who voted
- What they voted
- When they voted
- Their role and vote weight
- PR details
PR Merges
- Who merged
- Which PR
- Weighted vote score
- Merge commit hash
Vetoes
- Who vetoed
- Which PR
- Reason for veto
- Timestamp
Overrides
- Who overrode
- Which PR
- Reason for override
- Original decision
Policy Changes
- What changed
- Old value
- New value
- Who changed it
- Reason

Audit Entry Structure

Each entry in the audit log has this structure:

{
  "id": "GOVERNANCE_VOTE_1762471624918_enhhmm",
  "timestamp": "2025-11-06T23:27:04.918Z",
  "event_type": "VOTE_CAST",
  "actor": "asymcrypto",
  "actor_role": "founder",
  "action": "Voted approve on PR #100",
  "details": {
    "pr_number": 100,
    "vote": "approve",
    "vote_weight": 100,
    "comment": "Looks good to me",
    "pr_type": "normal"
  },
  "metadata": {
    "repository": "asymcrypto/gitforge-template",
    "workflow_run_id": "12345"
  },
  "hash": "e49fb39de5da655f999ea5404248d639018a74ee1f1d5e4d2a4f85adbcc4b6af"
}

Cryptographic Hashing

Each audit entry is cryptographically hashed using SHA-256:

Purpose: Detect tampering
How: Hash is computed from entry data
Verification: Recalculate hash and compare with stored value
Integrity: If hashes don't match, entry has been modified

Querying the Audit Log

You can query the audit log for specific information:

// Get all votes for PR #100
const pr100Votes = logger.getEntriesForPR(100);

// Get all actions by a specific actor
const founderActions = logger.getEntriesByActor('asymcrypto');

// Get all vetoes
const vetoes = logger.getEntriesByEventType('VETO_CAST');

// Get entries within a date range
const thisMonth = logger.getEntriesByDateRange(startDate, endDate);

Compliance Reporting

Generate compliance reports for audits:

// Export compliance report for Q1 2025
const report = logger.exportComplianceReport(
  new Date('2025-01-01'),
  new Date('2025-03-31')
);

// Report includes:
// - Total votes cast
// - Total merges
// - Total vetoes
// - Total overrides
// - All entries with full details

⚙️ Configuration Guide

Governance Configuration File

Edit github/GOVERNANCE_CONFIG.json to customize your governance:

{
  "version": "1.0.0",
  "governance_model": "weighted_voting",
  "voting_rules": {
    "merge_approval_threshold": 50,
    "voting_method": "weighted_majority"
  },
  "maintainer_roles": {
    "founder": {
      "vote_weight": 100,
      "can_merge": true,
      "can_override": true,
      "can_veto": true
    },
    "lead_maintainer": {
      "vote_weight": 75,
      "can_merge": true,
      "can_override": false,
      "can_veto": true
    }
    // ... more roles
  },
  "maintainers": [
    {
      "github_username": "asymcrypto",
      "role": "founder",
      "active": true
    }
    // ... more maintainers
  ],
  "special_rules": {
    "bounty_prs": {
      "weighted_vote_threshold": 60,
      "require_additional_review": true
    },
    "security_prs": {
      "weighted_vote_threshold": 75,
      "require_founder_approval": true
    }
  }
}

Adding a New Maintainer

Edit github/GOVERNANCE_CONFIG.json
Add entry to maintainers array:

{
  "github_username": "new-maintainer",
  "role": "maintainer",
  "vote_weight": 50,
  "active": true,
  "joined_date": "2025-11-06",
  "permissions": {
    "can_merge": true,
    "can_override": false,
    "can_veto": false,
    "can_modify_governance": false
  }
}

Commit and push changes
New maintainer can now vote on PRs

Changing Vote Thresholds

Edit github/GOVERNANCE_CONFIG.json
Update voting_rules.merge_approval_threshold:

{
  "voting_rules": {
    "merge_approval_threshold": 60  // Changed from 50
  }
}

This change is logged in the governance audit
All future votes use the new threshold

Customizing Special Rules

Define different rules for different PR types:

{
  "special_rules": {
    "bounty_prs": {
      "weighted_vote_threshold": 60,
      "require_additional_review": true,
      "additional_reviewers_needed": 1
    },
    "security_prs": {
      "weighted_vote_threshold": 75,
      "require_founder_approval": true,
      "additional_reviewers_needed": 2
    },
    "governance_prs": {
      "weighted_vote_threshold": 80,
      "require_founder_approval": true,
      "additional_reviewers_needed": 2
    }
  }
}

🏆 Best Practices

For Maintainers

Be Transparent
- Always provide comments when voting
- Explain your reasoning
- Reference relevant issues or discussions
Use Veto Sparingly
- Veto only for critical issues
- Always provide a reason
- Discuss with team before vetoing
Review Thoroughly
- Read PR description and code
- Check for security issues
- Verify tests pass
- Consider impact on other systems
Monitor Governance
- Review audit log regularly
- Check vote patterns
- Identify problematic trends
- Discuss governance improvements

For Contributors

Understand Governance
- Read this guide
- Know the voting thresholds
- Understand special rules for your PR type
Prepare Your PR
- Clear description
- Comprehensive tests
- Updated documentation
- Linked issue
Engage with Reviewers
- Respond to feedback promptly
- Ask for clarification if needed
- Make requested changes quickly
- Thank reviewers for their time
Respect the Process
- Don't pressure for merges
- Accept veto decisions
- Learn from rejections
- Improve for next time

For Project Leads

Set Clear Policies
- Document governance rules
- Explain voting thresholds
- Define PR types and rules
- Communicate changes
Maintain Fairness
- Ensure consistent voting
- Prevent favoritism
- Review audit log for patterns
- Address concerns promptly
Build Trust
- Be transparent
- Explain decisions
- Listen to feedback
- Make improvements based on input
Monitor Health
- Track merge times
- Monitor contributor satisfaction
- Review governance metrics
- Adjust policies as needed

🔧 Troubleshooting

PR Not Merging Despite Approval

Possible Causes:

Weighted vote score below threshold
Someone has vetoed
CI/CD checks failed
Required reviews not met

Solution:

Check weighted vote score: PR #100 has 45% approval (threshold: 50%)
Look for vetoes in audit log
Verify all CI checks pass
Ensure all required reviewers have voted

Veto Seems Unfair

Process:

Discuss with the vetoer
Address their concerns
Request veto withdrawal if appropriate
If necessary, founder can override

Prevention:

Establish veto guidelines
Require veto comments
Review veto patterns in audit log
Discuss governance improvements

Audit Log Not Updating

Possible Causes:

Workflow not triggered
Permissions issue
File write error
JSON syntax error

Solution:

Check workflow logs in Actions tab
Verify repository permissions
Check for JSON errors: jq . github/GOVERNANCE_AUDIT.json
Manually trigger workflow if needed

Maintainer Can't Vote

Possible Causes:

Not in maintainers list
Role not configured
Workflow not running
GitHub permissions issue

Solution:

Verify in GOVERNANCE_CONFIG.json
Check role configuration
Manually trigger weighted-voting-check workflow
Verify GitHub Actions permissions

📊 Monitoring Governance

Key Metrics to Track

Metric	What It Means	Target
Average Merge Time	How long PRs take to merge	< 24 hours
Veto Rate	Percentage of PRs vetoed	< 5%
Override Rate	Percentage of overrides	< 1%
Voter Participation	Percentage of maintainers voting	> 80%
Vote Consensus	Percentage of unanimous votes	> 70%

Governance Dashboard

View governance metrics at: https://[user].github.io/[repo]/governance.html (coming soon)

Shows:

Recent votes and merges
Veto history
Override history
Voting patterns by maintainer
PR type distribution

🔐 Security Considerations

Protecting Your Governance

Limit Maintainer Access
- Only trusted people should be maintainers
- Review regularly
- Remove inactive maintainers
Monitor Audit Log
- Review regularly
- Look for unusual patterns
- Investigate suspicious activity
Secure Credentials
- Never commit secrets
- Use GitHub Secrets for API keys
- Rotate credentials regularly
Backup Audit Log
- Export regularly
- Store securely
- Verify integrity

📞 Support

For questions or issues with governance:

Documentation: This guide
Issues: Create a GitHub issue
Discussions: GitHub Discussions
Enterprise: enterprise@gitforge.dev

Built with ❤️ by the GitForge Team

Making governance transparent, fair, and auditable

FilesExpand file tree

GOVERNANCE_GUIDE.md

Latest commit

History

GOVERNANCE_GUIDE.md

File metadata and controls

🗳️ GitForge Governance Guide

📋 Table of Contents

🎯 Overview

Key Principles

🏛️ Governance Model

Role-Based Hierarchy

How Voting Works

Voting Thresholds

🗳️ Weighted Voting System

Understanding Vote Weights

Vote Types

Veto Power

Override Capability

📋 Governance Audit Log

What Gets Logged

Audit Entry Structure

Cryptographic Hashing

Querying the Audit Log

Compliance Reporting

⚙️ Configuration Guide

Governance Configuration File

Adding a New Maintainer

Changing Vote Thresholds

Customizing Special Rules

🏆 Best Practices

For Maintainers

For Contributors

For Project Leads

🔧 Troubleshooting

PR Not Merging Despite Approval

Veto Seems Unfair

Audit Log Not Updating

Maintainer Can't Vote

📊 Monitoring Governance

Key Metrics to Track

Governance Dashboard

🔐 Security Considerations

Protecting Your Governance

📞 Support