diff --git a/README.md b/README.md index f06e76d..e38870e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,36 @@ -# gh-abcs-admin -> The GitHub ABCs admin training with templates, examples, hands-on labs and additional learning resources. +# GitHub Administration & Governance Workshop (L400) -## Examples & Hands-on Labs +> **Advanced Workshop** | Expert-level training for GitHub Enterprise Cloud administration, governance, and best practices. This workshop covers enterprise hierarchy, organization strategies, identity management (including Enterprise Managed Users), policy enforcement, security compliance, and the GitHub Well-Architected Framework. + +## Workshop Documentation + +Comprehensive L400-level technical documentation for GitHub Enterprise Cloud administration and governance. + +### Enterprise Administration +- [📘 Enterprise Hierarchy](docs/01-enterprise-hierarchy.md) - GHEC structure, roles, and multi-org management +- [🏢 Organization Strategies](docs/02-organization-strategies.md) - Single/multi-org patterns, red-green-sandbox-archive + +### Identity & Access Management +- [🔐 Identity & Access Management](docs/03-identity-access-management.md) - SAML SSO, SCIM, enterprise type selection +- [⭐ Enterprise Managed Users (EMU)](docs/04-enterprise-managed-users.md) - EMU deep dive, advantages, best practices + +### Teams & Permissions +- [👥 Teams and Permissions](docs/05-teams-permissions.md) - Team structures, nested teams, permission models +- [📋 Policy Inheritance](docs/06-policy-inheritance.md) - Enterprise → Org → Repo policy enforcement + +### Repository Governance +- [📦 Repository Governance](docs/07-repository-governance.md) - Rulesets, branch protection, templates +- [🔒 Security & Compliance](docs/08-security-compliance.md) - GHAS, code scanning, audit logs + +### Best Practices & Architecture +- [✅ Best Practices & WAF](docs/09-best-practices-waf.md) - GitHub Well-Architected Framework principles +- [🏗️ Reference Architecture](docs/10-reference-architecture.md) - Architecture diagrams and patterns + +--- + +## Hands-on Labs + +Practical exercises to reinforce GitHub administration concepts. ### Hands-on Labs Setup - [ ] [Lab Setup](/labs/setup.md) diff --git a/docs/01-enterprise-hierarchy.md b/docs/01-enterprise-hierarchy.md new file mode 100644 index 0000000..4e8f34a --- /dev/null +++ b/docs/01-enterprise-hierarchy.md @@ -0,0 +1,706 @@ +# GitHub Enterprise Cloud Hierarchy + +## Overview + +GitHub Enterprise Cloud (GHEC) provides a multi-tiered organizational structure that enables large organizations to manage multiple teams, projects, and repositories under a unified enterprise account. This hierarchical model facilitates centralized governance, billing, and policy enforcement while maintaining organizational autonomy and flexibility. + +The enterprise account serves as the top-level container, providing enterprise administrators with visibility and control across all member organizations, enabling strategic oversight of development activities, security posture, and resource allocation. + +## Enterprise Account Capabilities + +An enterprise account on GitHub Enterprise Cloud delivers advanced administrative, security, and compliance capabilities designed for large-scale operations: + +### Core Enterprise Features + +**Centralized Management** +- Unified dashboard providing real-time visibility across all organizations +- Consolidated user management with enterprise-level identity provisioning +- Single sign-on (SSO) enforcement via SAML 2.0 or OIDC +- Centralized billing with cost allocation and usage analytics + +**Security and Compliance** +- Enterprise-wide security policies and enforcement +- Advanced audit logging with 180-day retention (extendable via log streaming) +- IP allow lists at the enterprise level +- SSH certificate authority for cryptographic authentication +- SCIM provisioning for automated user lifecycle management + +**Policy Enforcement** +- Repository policy management across organizations +- Branch protection rules inheritance +- Required workflows for GitHub Actions +- Custom repository roles and permissions +- Dependency management and security advisories + +**Advanced Features** +- GitHub Advanced Security (GHAS) licensing and deployment +- Enterprise Managed Users (EMU) for complete identity control +- GitHub Connect for hybrid cloud/server environments +- Premium support with configurable SLA tiers + +## Hierarchy Levels + +The GitHub Enterprise Cloud architecture implements a three-tier hierarchy that balances centralized governance with distributed autonomy: + +```mermaid +graph TD + A[Enterprise Account] --> B[Organization 1] + A --> C[Organization 2] + A --> D[Organization N] + B --> E[Repository 1.1] + B --> F[Repository 1.2] + B --> G[Team Structure] + C --> H[Repository 2.1] + C --> I[Repository 2.2] + C --> J[Team Structure] + D --> K[Repository N.1] + D --> L[Repository N.2] + D --> M[Team Structure] + G --> N[Team Alpha] + G --> O[Team Beta] + J --> P[Team Gamma] + J --> Q[Team Delta] + M --> R[Team Omega] + + style A fill:#6e40c9 + style B fill:#0969da + style C fill:#0969da + style D fill:#0969da + style E fill:#2da44e + style F fill:#2da44e + style H fill:#2da44e + style I fill:#2da44e + style K fill:#2da44e + style L fill:#2da44e +``` + +### Enterprise Level + +The enterprise account represents the apex of the hierarchy and serves as the administrative and billing boundary. Key characteristics include: + +- **Scope:** Contains multiple organizations with unified governance +- **Ownership:** Managed by Enterprise Owners with super-admin privileges +- **Billing:** Consolidated invoicing across all organizations and users +- **Policies:** Top-level policy inheritance and enforcement +- **Visibility:** Aggregate insights and reporting across the enterprise +- **Identity:** Enterprise-level SSO configuration and authentication requirements + +### Organization Level + +Organizations function as logical groupings for teams, projects, and repositories. They provide: + +- **Autonomy:** Independent settings within enterprise policy constraints +- **Team Management:** Hierarchical team structures with nested teams +- **Access Control:** Organization-level roles and team-based permissions +- **Project Governance:** Organization-specific policies and workflows +- **Resource Ownership:** Repositories, projects, packages, and Actions workflows +- **Collaboration:** Shared context for related projects and teams + +Organizations inherit mandatory policies from the enterprise but can implement additional restrictions. This allows business units, divisions, or product lines to operate semi-independently while adhering to corporate standards. + +### Repository Level + +Repositories are the fundamental units of source code management and collaboration: + +- **Code Storage:** Git-based version control with full history +- **Access Management:** Granular permissions (Read, Triage, Write, Maintain, Admin) +- **Collaboration:** Issues, pull requests, discussions, and wikis +- **Automation:** GitHub Actions workflows, webhooks, and GitHub Apps +- **Security:** Dependabot, code scanning, secret scanning, and security advisories +- **Deployment:** Environments, deployment branches, and protection rules + +Repositories inherit policies from both the organization and enterprise levels, creating a defense-in-depth security model. + +## Enterprise Roles + +GitHub Enterprise Cloud implements a role-based access control (RBAC) model with specialized enterprise-level roles: + +### Enterprise Owner + +The Enterprise Owner role carries the highest level of administrative privileges across the entire enterprise account. + +**Capabilities:** +- Full administrative access to all enterprise settings and configurations +- Create, configure, and delete organizations within the enterprise +- Invite and remove enterprise members and administrators +- Configure enterprise-wide authentication and SSO requirements +- Manage enterprise billing settings and payment methods +- Set and enforce organization policies across the enterprise +- Access enterprise audit logs and security reports +- Configure IP allow lists and security policies +- Manage GitHub Advanced Security licensing and deployment +- Set up required workflows and organization standards + +**Use Cases:** +- C-level executives with ultimate accountability +- Senior IT leadership responsible for platform governance +- Security architects defining enterprise-wide security posture +- Compliance officers requiring audit and oversight capabilities + +**Best Practices:** +- Limit to 3-5 individuals maximum for security and accountability +- Require hardware security keys (U2F/WebAuthn) for authentication +- Implement just-in-time access patterns where possible +- Regular access reviews (quarterly minimum) +- Document all Enterprise Owner actions in an external system + +### Billing Manager + +Billing Managers have specialized access limited to financial and subscription management: + +**Capabilities:** +- View and manage enterprise billing settings +- Update payment methods and billing contacts +- Access billing history and invoices +- View license usage and consumption reports +- Download usage data for cost allocation +- Manage spending limits for GitHub Actions and Packages + +**Restrictions:** +- No access to enterprise security or administrative settings +- Cannot modify organizations, repositories, or user access +- Cannot view or modify enterprise policies +- Cannot access audit logs (unless separately granted) + +**Use Cases:** +- Finance team members managing software expenditures +- Procurement specialists tracking license consumption +- Budget managers requiring cost visibility +- Accounting personnel processing invoices + +### Enterprise Member + +Enterprise Members are users who belong to at least one organization within the enterprise. + +**Default Capabilities:** +- Single sign-on authentication via enterprise SSO +- Visibility determined by organization membership +- Access to repositories based on organization/team permissions +- Subject to enterprise-wide policies and restrictions + +**Status Management:** +- Membership can be direct or via IdP group synchronization +- Outside collaborators are not enterprise members +- Member status affects licensing and compliance reporting + +## Enterprise Settings and Dashboard Navigation + +The enterprise dashboard serves as the central command center for enterprise administration. + +### Accessing the Enterprise Dashboard + +1. Navigate to `https://github.com/enterprises/[enterprise-slug]` +2. Click your profile photo → "Your enterprises" +3. Select the appropriate enterprise from the list + +### Dashboard Components + +**Overview Tab** +- Summary statistics: organizations, repositories, members +- Recent activity feed across all organizations +- License consumption and availability +- Security alerts and recommendations +- Compliance status and pending actions + +**Organizations Tab** +- List of all organizations with key metrics +- Organization creation and configuration +- Policy compliance indicators +- Quick actions for common tasks + +**People Tab** +- Enterprise member roster with role assignments +- Pending invitations and access requests +- SCIM provisioning status and sync errors +- Member activity and audit trail + +**Settings Tab** + +The Settings area provides access to critical configuration options: + +**Authentication & Security** +- SAML/OIDC single sign-on configuration +- Two-factor authentication enforcement +- SSH certificate authority setup +- IP allow list management +- Session duration and timeout policies + +**Policy Management** +- Repository management policies +- Base permissions for member organizations +- Repository creation restrictions +- Repository deletion and transfer policies +- Repository visibility constraints +- Commit signature requirements + +**GitHub Actions Policies** +- Actions usage limits and spending caps +- Allowed actions and verified creator restrictions +- Required workflows for organizational compliance +- Runner group management and registration + +**Audit Log** +- Searchable event log with 180+ day retention +- Export capabilities (JSON, CSV) +- Real-time event streaming to SIEM platforms +- Compliance reporting and anomaly detection + +**Billing** +- Current plan and subscription details +- License allocation and usage metrics +- Payment methods and billing contacts +- Usage reports for Actions, Packages, and Storage +- Cost allocation by organization + +## Multi-Organization Management Patterns + +Enterprises typically adopt one of several organizational structures based on their business model and operational requirements: + +### Pattern 1: Business Unit Segregation + +Organizations align with major business units or divisions: + +```mermaid +graph LR + A[Enterprise: Contoso Corp] --> B[Org: Consumer Division] + A --> C[Org: Enterprise Division] + A --> D[Org: Platform Engineering] + + B --> B1[Consumer Apps] + B --> B2[Mobile Team] + + C --> C1[B2B Products] + C --> C2[Enterprise Solutions] + + D --> D1[Infrastructure] + D --> D2[DevOps Tools] + + style A fill:#6e40c9 + style B fill:#0969da + style C fill:#0969da + style D fill:#0969da +``` + +**Characteristics:** +- Clear ownership boundaries +- Independent budgets and reporting +- Autonomous decision-making +- Distinct compliance requirements + +**Governance Approach:** +- Enterprise sets minimum security baseline +- Organizations customize workflows and processes +- Dedicated organization admins per business unit +- Cross-organization collaboration via outside collaborators + +### Pattern 2: Product/Project-Based + +Organizations represent major products or strategic initiatives: + +**Characteristics:** +- Product-centric ownership +- Cross-functional teams within each organization +- Shared services organizations for platform capabilities +- Temporary organizations for time-bound initiatives + +**Governance Approach:** +- Product owners have organization admin rights +- Shared libraries via internal packages +- Reusable Actions workflows across products +- Central platform team maintains shared services + +### Pattern 3: Environment Segregation + +Organizations separate production and non-production workloads: + +**Characteristics:** +- Production organization with strict controls +- Development/staging organizations with relaxed policies +- Air-gapped security boundaries +- Promotion workflows between environments + +**Governance Approach:** +- Enhanced security policies for production organization +- Restricted membership for production access +- Automated promotion via GitHub Actions +- Audit logging and change approval requirements + +### Pattern 4: Security-Driven Isolation + +Organizations segregate based on data classification or compliance requirements: + +**Characteristics:** +- Public-facing projects in dedicated organization +- Highly regulated projects in compliant organization +- Open source contributions isolated from proprietary code +- Third-party integrations restricted by organization + +**Governance Approach:** +- Defense in depth with multiple policy layers +- Strict access controls and regular reviews +- Enhanced monitoring and alerting +- Compliance attestation per organization + +## Enterprise Admin Responsibilities Flow + +The following diagram illustrates the key responsibilities and decision flows for enterprise administrators: + +```mermaid +flowchart TD + Start([Enterprise Admin Activities]) --> Auth{Authentication & Access} + + Auth --> SSO[Configure SSO/SAML] + Auth --> MFA[Enforce 2FA] + Auth --> IP[Manage IP Allowlists] + + SSO --> PolicyMgmt{Policy Management} + MFA --> PolicyMgmt + IP --> PolicyMgmt + + PolicyMgmt --> RepoPol[Repository Policies] + PolicyMgmt --> ActionPol[Actions Policies] + PolicyMgmt --> SecPol[Security Policies] + + RepoPol --> OrgMgmt{Organization Management} + ActionPol --> OrgMgmt + SecPol --> OrgMgmt + + OrgMgmt --> CreateOrg[Create/Configure Organizations] + OrgMgmt --> MemberMgmt[Manage Members] + OrgMgmt --> Billing[Monitor Billing] + + CreateOrg --> Compliance{Compliance & Audit} + MemberMgmt --> Compliance + Billing --> Compliance + + Compliance --> AuditLog[Review Audit Logs] + Compliance --> Reports[Generate Reports] + Compliance --> Alerts[Monitor Security Alerts] + + AuditLog --> Remediate{Remediation Needed?} + Reports --> Remediate + Alerts --> Remediate + + Remediate -->|Yes| Investigate[Investigate & Fix] + Remediate -->|No| Monitor[Continue Monitoring] + + Investigate --> Document[Document Changes] + Monitor --> Document + + Document --> End([Ongoing Governance]) + + style Start fill:#6e40c9 + style End fill:#6e40c9 + style Auth fill:#0969da + style PolicyMgmt fill:#0969da + style OrgMgmt fill:#0969da + style Compliance fill:#0969da + style Remediate fill:#bf8700 +``` + +### Key Administrative Workflows + +**Daily Operations** +1. Monitor security alerts across organizations +2. Review audit log for anomalous activities +3. Process access requests and membership changes +4. Respond to support escalations from organization admins + +**Weekly Activities** +1. Review license consumption and trends +2. Analyze GitHub Actions usage and costs +3. Validate policy compliance across organizations +4. Update IP allow lists for new office locations or VPN endpoints + +**Monthly Governance** +1. Access recertification for Enterprise Owners +2. Audit organization admin assignments +3. Review and optimize repository policies +4. Generate compliance reports for stakeholders +5. Evaluate new GitHub features for adoption + +**Quarterly Strategic Reviews** +1. Enterprise architecture alignment assessment +2. Security posture evaluation and improvements +3. Disaster recovery and business continuity testing +4. Budget planning and license forecasting +5. Training and enablement program effectiveness + +## Enterprise Audit Log and Compliance Features + +The enterprise audit log provides comprehensive visibility into all administrative and security-relevant activities across the enterprise. + +### Audit Log Capabilities + +**Event Coverage** +- Authentication events (SSO, 2FA, login attempts) +- Administrative actions (role changes, policy modifications) +- Repository operations (creation, deletion, transfer, visibility changes) +- Access control changes (team membership, permissions grants) +- Security events (secret detection, security policy changes) +- Integration activities (OAuth apps, GitHub Apps, webhooks) + +**Retention and Export** +- 180-day retention in GitHub UI (extendable via export) +- Real-time streaming to SIEM platforms via webhooks +- Bulk export in JSON or CSV formats +- Programmatic access via REST API + +**Search and Filtering** +- Advanced query syntax with boolean operators +- Filter by actor, action, organization, repository, timestamp +- Saved searches for common compliance queries +- Integration with enterprise reporting tools + +### Log Streaming Integration + +For long-term retention and advanced analytics, configure audit log streaming: + +**Supported Destinations** +- Amazon S3 for cost-effective archival +- Azure Event Hubs for real-time processing +- Splunk for security information and event management (SIEM) +- Datadog for observability and alerting +- Google Cloud Storage for GCP-native workflows + +**Configuration Steps** +1. Navigate to Enterprise Settings → Audit log +2. Select "Stream logs" and choose destination +3. Provide endpoint credentials (access keys, connection strings) +4. Configure event filters (optional) +5. Test connection and verify event delivery +6. Enable streaming for continuous delivery + +**Common Use Cases** +- SOC 2, ISO 27001, and compliance reporting +- Security incident investigation and forensics +- User behavior analytics (UBA) and anomaly detection +- Governance dashboards and executive reporting +- Automated alerting on policy violations + +### Compliance Monitoring + +**Key Compliance Metrics** +- Percentage of users with 2FA enabled +- SSO adoption rate across organizations +- Repository policy compliance scores +- Security vulnerability remediation SLAs +- Access review completion rates + +**Automated Compliance Checks** +- GitHub Actions workflows for policy validation +- Required workflows for compliance gates +- Branch protection rule enforcement +- Commit signature verification requirements +- Dependency vulnerability scanning coverage + +**Regulatory Frameworks** +- SOC 2 Type II attestation support +- GDPR data processing agreement +- HIPAA compliance with BAA available +- FedRAMP compliance (GovCloud) +- ISO 27001, 27017, 27018 certifications + +## Best Practices for Enterprise Administration + +### Security Hardening + +1. **Enforce Strong Authentication** + - Require 2FA for all enterprise members + - Mandate hardware security keys for admins + - Configure SSO with modern protocols (SAML 2.0, OIDC) + - Implement conditional access policies + +2. **Principle of Least Privilege** + - Minimize Enterprise Owner assignments + - Use organization-level admins for delegation + - Implement just-in-time access workflows + - Regular access reviews and recertification + +3. **Defense in Depth** + - Layer policies at enterprise and organization levels + - Use IP allow lists for sensitive organizations + - Enable GitHub Advanced Security across repositories + - Implement required workflows for compliance + +### Operational Excellence + +1. **Automation and Infrastructure as Code** + - Use Terraform provider for GitHub Enterprise + - Automate organization creation and configuration + - Implement GitOps for policy management + - Self-service workflows for common requests + +2. **Monitoring and Alerting** + - Stream audit logs to SIEM platform + - Configure alerts for high-risk events + - Dashboard license consumption trends + - Monitor GitHub Actions minutes usage + +3. **Documentation and Training** + - Maintain runbooks for common scenarios + - Document organizational structure decisions + - Training programs for organization admins + - Regular communication of policy updates + +### Scalability Planning + +1. **Capacity Management** + - Monitor license consumption trends + - Forecast growth based on hiring plans + - Plan for GitHub Actions minutes scaling + - Budget for storage and bandwidth overages + +2. **Organizational Structure Evolution** + - Review organization structure quarterly + - Plan for mergers, acquisitions, and divestitures + - Balance autonomy with governance overhead + - Consider splitting large organizations strategically + +## Advanced Topics + +### Enterprise Managed Users (EMU) + +EMU provides complete lifecycle management of user identities through your Identity Provider: + +**Key Characteristics** +- GitHub manages user accounts on your behalf +- Users can only authenticate via enterprise SSO +- No personal GitHub account interactions +- Usernames follow configurable pattern (e.g., `octocat_corp`) +- Complete isolation from public GitHub + +**Trade-offs** +- Enhanced security and control +- Simplified compliance and auditing +- Limited external collaboration workflows +- Cannot contribute to public repositories outside enterprise +- Requires migration planning for existing enterprises + +### GitHub Connect + +GitHub Connect enables hybrid deployments connecting GitHub Enterprise Server to GitHub Enterprise Cloud: + +**Capabilities** +- Unified search across cloud and server instances +- Dependency insights from GitHub Advisory Database +- GitHub Actions access to cloud-hosted runners +- Single sign-on spanning both environments + +**Use Cases** +- Gradual cloud migration strategies +- Regulatory requirements for on-premises code +- Hybrid workforce with distributed access needs +- Air-gapped environments with periodic sync + +## Migration and Onboarding Strategies + +### Enterprise Onboarding Checklist + +**Phase 1: Planning (Weeks 1-2)** +- [ ] Define organizational structure +- [ ] Identify Enterprise Owners and Billing Managers +- [ ] Plan SSO integration and authentication strategy +- [ ] Design IP allow list requirements +- [ ] Establish policy framework and governance model + +**Phase 2: Configuration (Weeks 3-4)** +- [ ] Configure enterprise SSO and test authentication +- [ ] Create initial organizations +- [ ] Set enterprise-level policies +- [ ] Configure audit log streaming +- [ ] Establish billing alerts and spending limits + +**Phase 3: Migration (Weeks 5-8)** +- [ ] Migrate existing organizations (if applicable) +- [ ] Provision users via SCIM or bulk invite +- [ ] Transfer repository ownership +- [ ] Configure GitHub Advanced Security +- [ ] Test workflows and integrations + +**Phase 4: Enablement (Weeks 9-12)** +- [ ] Train organization administrators +- [ ] Document support escalation procedures +- [ ] Establish governance review cadence +- [ ] Launch internal developer portal +- [ ] Collect feedback and iterate + +### Organization Migration Patterns + +**Approach 1: Repository Transfer** +- Transfer repositories to new organizations within enterprise +- Preserves history, issues, and pull requests +- Updates integrations and webhooks automatically +- Minimal disruption to development workflows + +**Approach 2: Fork and Redirect** +- Fork repositories to new organization +- Update repository settings to archive old repos +- Redirect teams to new locations +- Allows gradual migration and rollback capability + +**Approach 3: Fresh Start** +- Create new repositories in target organizations +- Migrate code via git operations (preserving history) +- Reconfigure integrations and CI/CD pipelines +- Opportunity to clean up legacy configurations + +## Troubleshooting Common Issues + +### SSO Configuration Problems + +**Issue:** Users cannot authenticate via SSO +- Verify SAML/OIDC metadata URL is accessible +- Check NameID format matches configuration +- Validate signing certificate is not expired +- Review IdP group mappings for correctness + +**Issue:** Some users bypass SSO requirement +- Check for pre-existing personal access tokens +- Verify SSO enforcement is enabled at enterprise level +- Review outside collaborator access patterns +- Audit organization membership for exceptions + +### Policy Enforcement Gaps + +**Issue:** Repositories not complying with policies +- Confirm policies are enabled at enterprise level +- Check for organization-level policy overrides +- Review repository exemption lists +- Verify policy synchronization has completed + +**Issue:** Required workflows not executing +- Validate workflow file location and syntax +- Check organization settings for workflow requirements +- Review runner availability and labels +- Examine workflow run logs for errors + +### Licensing and Billing Concerns + +**Issue:** Higher than expected license consumption +- Audit enterprise member list for inactive users +- Check for outside collaborators consuming licenses +- Review deprovisioning automation effectiveness +- Identify dormant accounts for removal + +**Issue:** GitHub Actions minutes exhausted +- Review top consuming workflows and repositories +- Optimize workflow efficiency (caching, concurrency) +- Consider self-hosted runners for high-volume jobs +- Adjust spending limits or increase minutes allocation + +## References + +This document is based on official GitHub documentation and resources: + +- [GitHub Enterprise Cloud Documentation](https://docs.github.com/en/enterprise-cloud@latest/admin) - Comprehensive administration guide for GHEC +- [Enterprise Onboarding Guide](https://docs.github.com/en/enterprise-cloud@latest/enterprise-onboarding) - Official onboarding pathways and best practices +- [Administration and Governance Learning Path](https://resources.github.com/learn/pathways/administration-governance/essentials/administration-governance-github-enterprise-cloud/) - GitHub's official training resources for enterprise administration +- [Enterprise Accounts Overview](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/about-enterprise-accounts) - Enterprise account structure and capabilities +- [Managing Enterprise Roles](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise) - Role-based access control documentation +- [Enterprise Audit Log](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise) - Audit logging and compliance features +- [Enterprise Policies](https://docs.github.com/en/enterprise-cloud@latest/admin/policies) - Policy management and enforcement + +--- + +*This document is maintained as part of the GitHub Enterprise Cloud Administration learning path. For questions or contributions, please refer to the repository guidelines.* diff --git a/docs/02-organization-strategies.md b/docs/02-organization-strategies.md new file mode 100644 index 0000000..9b4cb05 --- /dev/null +++ b/docs/02-organization-strategies.md @@ -0,0 +1,1021 @@ +# Organization Design Patterns and Strategies + +## Overview + +Organization architecture represents one of the most critical design decisions in GitHub Enterprise Cloud (GHEC) deployment. The organizational structure directly impacts security boundaries, policy enforcement, cost allocation, compliance posture, and operational efficiency. This document provides expert-level guidance on selecting, implementing, and evolving organization design patterns for enterprise-scale GitHub deployments. + +Organizations in GHEC serve as administrative and security boundaries within an enterprise account. They encapsulate repositories, teams, members, and policies while providing isolation for billing, audit, and compliance purposes. The choice between single and multi-organization architectures fundamentally shapes how your enterprise manages access control, enforces governance, and scales development operations. + +## Single Organization Pattern + +### Architecture Overview + +The single organization pattern consolidates all repositories, teams, and members under one organizational unit within the enterprise account. This unified approach maximizes collaboration and simplifies administration while maintaining enterprise-level governance through centralized policies. + +```mermaid +graph TD + A[Enterprise Account] --> B[Single Organization] + B --> C[Development Teams] + B --> D[QA Teams] + B --> E[Operations Teams] + C --> F[Product Repos] + D --> G[Test Repos] + E --> H[Infrastructure Repos] + B --> I[All Members] + B --> J[Unified Policies] + B --> K[Shared Resources] + + style A fill:#e1f5ff + style B fill:#d4edda + style J fill:#fff3cd +``` + +### When to Use Single Organization + +**Optimal Use Cases:** +- **Small to Medium Enterprises** (< 500 developers): Administrative overhead remains manageable with unified governance +- **Highly Collaborative Environments**: Cross-functional teams require frequent repository access across product lines +- **Homogeneous Compliance Requirements**: Single regulatory framework applies uniformly across all development activities +- **Centralized Security Model**: Unified security posture with consistent scanning, secrets management, and vulnerability response +- **Startup to Scale-up Phase**: Rapid growth environments where organizational boundaries are still fluid +- **Platform Engineering Teams**: Shared platform services require universal access patterns + +### Advantages + +**Administrative Efficiency** +- Single point of administration for organization settings, integrations, and applications +- Unified audit log for comprehensive security monitoring +- Simplified user and team management through consolidated IdP synchronization +- Reduced context switching for administrators and users +- Single GitHub App installation scope reduces integration complexity + +**Collaboration Benefits** +- Frictionless repository discovery through unified namespace +- Internal repositories enable innersource patterns across all teams +- Simplified CODEOWNERS configuration with organization-wide team references +- Unified discussions, projects, and dependency graphs +- Cross-team code reuse without fork/transfer overhead + +**Cost Optimization** +- Single set of GitHub Actions shared runners (organization-level) +- Consolidated GitHub Advanced Security (GHAS) license utilization +- Simplified billing analysis and showback reporting +- Reduced administrative licensing costs + +**Technical Advantages** +- Organization-level repository rulesets apply uniformly +- Shared secrets and variables for GitHub Actions +- Unified Dependabot configuration and security policies +- Single GitHub Packages namespace and artifact management +- Consolidated organization insights and metrics + +### Disadvantages and Limitations + +**Scaling Challenges** +- **Repository Sprawl**: Discovery becomes difficult as repository count exceeds 1,000+ +- **Team Management Complexity**: Nested team hierarchies become unwieldy beyond 100 teams +- **Permission Model Limitations**: Base permissions apply globally, limiting defense-in-depth +- **Audit Log Volume**: High-velocity organizations generate massive audit data requiring streaming +- **API Rate Limits**: Shared organization-level rate limits may impact automation + +**Security Concerns** +- **Reduced Blast Radius Control**: Compromised credentials grant access to entire organization +- **Uniform Security Posture**: Cannot enforce graduated security controls by sensitivity level +- **Internal Repository Visibility**: All members see all internal repositories by default +- **Shared Attack Surface**: Single SAML/SCIM configuration represents critical dependency +- **Compliance Boundaries**: Cannot isolate regulated workloads (PCI, HIPAA, FedRAMP) effectively + +**Operational Constraints** +- **Change Management Risk**: Organization-level policy changes impact all repositories simultaneously +- **Disaster Recovery Complexity**: Single organization requires comprehensive backup strategy +- **Migration Friction**: Extracting business units later requires complex repository transfers +- **Limited Cost Allocation**: Granular chargeback requires external tooling and tagging discipline + +### Scaling Considerations + +**Growth Thresholds and Mitigation Strategies** + +| Metric | Threshold | Impact | Mitigation Strategy | +|--------|-----------|--------|---------------------| +| Repositories | 1,000+ | Discovery degradation | Topic taxonomy, repository templates, naming conventions | +| Teams | 100+ | Management complexity | Team sync with IdP groups, flat structure preference | +| Members | 500+ | Permission sprawl | Custom repository roles, CODEOWNERS enforcement | +| Daily Commits | 10,000+ | Audit log volume | Enable log streaming to SIEM, implement retention policies | +| CI/CD Minutes | 1M+/month | Cost and queueing | Self-hosted runners, organization-level concurrency limits | + +**Technical Scaling Patterns** + +**Repository Organization Strategies** +- **Topic-Based Discovery**: Enforce topic taxonomy for repository categorization (`team:platform`, `tier:1`, `language:java`) +- **Naming Conventions**: Implement hierarchical naming schemes (`platform-api-gateway`, `mobile-ios-app`, `infra-terraform-modules`) +- **Template Repositories**: Standardize repository creation with pre-configured settings, security scanning, and CI/CD pipelines +- **Repository Archival Policy**: Automated archival of inactive repositories (90+ days no commits) to reduce clutter + +**Team Structure Patterns** +- **Minimize Nesting**: Prefer flat team structures; excessive nesting (>3 levels) complicates permission reasoning +- **Team Sync**: Leverage IdP group synchronization to delegate team management to HR/IT systems +- **Team Size Optimization**: Keep teams under 50 members; larger groups should be split functionally +- **Maintainer Distribution**: Designate multiple team maintainers (minimum 3) for business continuity + +**Permission Model Evolution** +- **Progressive Base Permissions**: Start with "No permission" base, grant explicit access through teams +- **Custom Repository Roles**: Define organization-specific roles (`security-reviewer`, `deployment-manager`, `read-plus-actions`) +- **CODEOWNERS Governance**: Enforce code review requirements through organization-level rulesets +- **Just-in-Time Access**: Implement temporary access workflows using GitHub Apps and API automation + +## Multi-Organization Patterns + +Multi-organization architectures leverage organizational boundaries as security, compliance, and operational isolation mechanisms. Each organization maintains independent settings, policies, and resources while remaining governed by enterprise-level controls. + +```mermaid +graph TD + A[Enterprise Account] --> B[Production Org] + A --> C[Development Org] + A --> D[Sandbox Org] + A --> E[Archive Org] + + B --> B1[Critical Systems] + B --> B2[Customer-Facing Apps] + B --> B3[Strict Policies] + + C --> C1[Feature Development] + C --> C2[Integration Testing] + C --> C3[Relaxed Policies] + + D --> D1[Innovation Projects] + D --> D2[Experiments] + D --> D3[Minimal Policies] + + E --> E1[Decommissioned Code] + E --> E2[Historical Archives] + E --> E3[Read-Only Access] + + style A fill:#e1f5ff + style B fill:#f8d7da + style C fill:#d1ecf1 + style D fill:#fff3cd + style E fill:#d6d8db +``` + +### Red/Green (Blue/Green) Pattern + +The Red/Green pattern (sometimes called Blue/Green) establishes strict separation between production and non-production environments using organizational boundaries. This pattern is derived from blue/green deployment strategies but applied at the organizational architecture level. + +**Architecture Characteristics** + +**Red Organization (Production)** +- **Purpose**: Production systems, customer-facing applications, revenue-generating services +- **Security Posture**: Maximum enforcement, zero-trust principles +- **Access Model**: Minimal privileges, time-bounded access, comprehensive audit logging +- **Change Control**: Mandatory peer review, required status checks, deployment approval gates +- **Compliance**: SOC 2, ISO 27001, industry-specific regulations (PCI DSS, HIPAA) + +**Green Organization (Development)** +- **Purpose**: Feature development, integration testing, staging environments +- **Security Posture**: Balanced security with developer velocity +- **Access Model**: Broader access for development teams, self-service capabilities +- **Change Control**: Lighter review requirements, faster iteration cycles +- **Compliance**: Development environment standards, non-production data handling + +**Policy Differentiation** + +| Policy Domain | Red (Production) | Green (Development) | +|---------------|------------------|---------------------| +| Branch Protection | Required reviews (2+), signed commits, status checks | Required reviews (1+), optional signing | +| Secret Scanning | Push protection enabled, custom patterns | Push protection disabled, alerts only | +| Actions Policies | Approved actions only, self-hosted runners | Public actions allowed, GitHub-hosted runners | +| External Collaborators | Prohibited | Allowed with time limits | +| Repository Visibility | Private only | Private and internal | +| GHAS Enforcement | All features required | Optional per repository | +| IP Allow Lists | Corporate network only | Corporate + remote access | +| Deployment Environments | Protection rules, approval gates | Self-service deployment | + +**Implementation Best Practices** + +**Code Promotion Pipeline** +1. Development occurs in Green organization repositories +2. Pull request workflow merges code to main branch +3. CI/CD pipeline packages artifacts (container images, binaries, packages) +4. Artifacts promoted to production artifact registry +5. Red organization references promoted artifacts in deployment pipelines +6. Infrastructure-as-Code (IaC) may be replicated or shared depending on trust model + +**Repository Strategy** +- **Option 1: Separate Repositories**: Maintain distinct repositories in each organization; promote artifacts only + - **Advantages**: Complete isolation, different team access patterns + - **Disadvantages**: Code duplication, synchronized repository settings + +- **Option 2: Branch-Based**: Single repository in Green, protected production branch + - **Advantages**: Unified history, simpler management + - **Disadvantages**: Production code in non-production organization + +**Access Management** +- **Separate Team Membership**: Production access requires explicit approval, separate IdP groups +- **Temporary Access Patterns**: Time-bounded production access using GitHub App automation +- **Break-Glass Procedures**: Emergency access protocols with mandatory incident tickets +- **Service Accounts**: Dedicated machine users for CI/CD with minimal scoped credentials + +**Use Cases** +- Regulated industries requiring environment separation (financial services, healthcare) +- Organizations with strict change control requirements (ITIL, CMMI Level 4-5) +- Enterprises with separate production operations teams +- Multi-tenant SaaS providers with customer isolation requirements + +### Sandbox Pattern + +The Sandbox organization provides a low-risk environment for innovation, experimentation, and learning without impacting production systems or development velocity. + +**Architecture Characteristics** + +**Purpose and Scope** +- Technology evaluation and proof-of-concept projects +- Developer training and certification programs +- Hackathons and innovation initiatives +- Third-party integration testing +- Open-source project contributions +- Interview and assessment environments + +**Security Model** +- **Isolation**: No connectivity to production or development systems +- **Data Restrictions**: Synthetic data only, no production data or credentials +- **Network Boundaries**: Separate network policies, no VPN/private link access +- **Access Control**: Self-service repository creation, relaxed permissions +- **Monitoring**: Basic audit logging, anomaly detection for abuse patterns + +**Policy Configuration** +- Minimal branch protection (optional peer review) +- Public repositories allowed (with approval workflow) +- GitHub Actions: Public marketplace access, generous compute quotas +- External collaborators: Allowed for partnership evaluations +- GitHub Packages: Separate registry, no promotion to production +- Advanced Security: Optional, typically disabled for cost optimization + +**Lifecycle Management** + +**Onboarding Process** +1. Developer submits sandbox request via issue template or portal +2. Automated provisioning creates time-bounded repository (30/60/90 day TTL) +3. Repository includes README template with sandbox policies and expiration date +4. Automated notification 7 days before expiration with renewal instructions + +**Graduation Path** +- Successful experiments promoted to Development organization via repository transfer +- Requires security review, code quality assessment, and architectural approval +- Repository transfer triggers automated policy application and security scan baseline + +**Automatic Cleanup** +- Scheduled GitHub Actions workflow archives inactive repositories (30 days no commits) +- Notification workflow alerts owners before deletion (7-day warning) +- Soft delete: Transfer to Archive organization before permanent deletion (90-day retention) + +**Cost Management** +- **Compute Quotas**: Per-user GitHub Actions minutes limits (e.g., 2,000 minutes/month) +- **Storage Quotas**: Repository size limits (1GB soft limit, alerts at 80%) +- **GHAS Exclusion**: Sandbox repositories excluded from GHAS license consumption +- **Spending Limits**: Organization-level spending caps for Actions and Packages + +**Use Cases** +- **Technology Evaluation**: Assessing new frameworks, languages, or tools before adoption +- **Developer Onboarding**: New hire training environments without production access risk +- **Hackathons**: Time-bounded innovation events with rapid iteration +- **Partner Integration**: Testing third-party APIs and services in isolation +- **Certification Labs**: Hands-on environments for internal training programs +- **Interview Assessments**: Candidate technical evaluations with consistent environments + +### Archive Pattern + +The Archive organization serves as a repository graveyard for decommissioned, historical, or reference code that must be retained for compliance, audit, or historical purposes. + +**Architecture Characteristics** + +**Purpose** +- Regulatory retention requirements (SOX, GDPR, industry-specific regulations) +- Historical reference for legacy system migrations +- IP protection and code provenance documentation +- Audit trail for security incident investigations +- Sunset application code bases +- Acquired company repositories post-integration + +**Security Posture** +- **Read-Only Access**: All repositories archived automatically on transfer +- **Limited Membership**: Minimal user access (compliance officers, legal, senior leadership) +- **Audit Logging**: Comprehensive access logging with extended retention (7+ years) +- **Encryption**: At-rest encryption for all archived content +- **Immutability**: Branch protection prevents force pushes or deletion + +**Access Control Model** + +**Tiered Access Levels** +1. **Legal/Compliance (Organization Owners)**: Full read access for discovery and export +2. **Historical Reference (Read Access)**: Engineers requiring legacy system understanding +3. **Audit/Security (Custom Role)**: Access to audit logs and repository metadata only +4. **External Auditors (Time-Bounded)**: Temporary read access via outside collaborators + +**Request Workflow** +- Access requires formal request with business justification +- Approval chain: Manager → Security → Compliance +- Time-bounded access grants (30/60/90 days) with automatic expiration +- Comprehensive audit logging of all read operations + +**Repository Lifecycle** + +**Transfer Criteria** +- Application sunset after customer migration complete +- Acquired company code post-integration (12-month stabilization period) +- Regulatory retention triggers (end of service date + retention period) +- Legacy platform deprecation (mainframe, deprecated language versions) +- Security incident preservation (immutable record for forensics) + +**Transfer Process** +1. Repository maintainer initiates transfer request via GitHub issue +2. Automated workflow validates completeness (README, LICENSE, documentation) +3. Metadata tagging (decommission date, business owner, retention period) +4. Transfer to Archive organization triggers automatic archival +5. Notification to organization members of new archived repository +6. Original organization retains redirect for 90 days + +**Retention and Disposal** + +**Retention Policies by Category** +| Content Type | Retention Period | Disposal Method | +|--------------|------------------|-----------------| +| Financial Systems | 7 years | Secure deletion with certificate | +| Healthcare (HIPAA) | 6 years | Secure deletion with audit log | +| General Business | 3-5 years | Standard deletion | +| IP/Patents | Indefinite | No disposal | +| Security Incidents | Indefinite | No disposal | + +**Disposal Process** +- Automated workflow identifies repositories exceeding retention period +- Legal review confirms no ongoing litigation or audit holds +- Secure deletion with cryptographic verification +- Disposal certificate generated and retained in compliance system + +**Cost Optimization** +- Archive organization excluded from GHAS licensing +- GitHub Actions disabled (no compute costs) +- GitHub Packages disabled (no storage costs for new artifacts) +- Storage costs minimal (Git repositories highly compressible) + +**Use Cases** +- **Post-Merger Integration**: Acquired company repositories after code consolidation +- **Legacy Platform Sunsets**: Mainframe, AS/400, or deprecated language code bases +- **Regulatory Compliance**: SOX 404, GDPR Article 17 (right to erasure), industry-specific retention +- **Security Forensics**: Incident response evidence preservation with chain of custody +- **IP Portfolio Management**: Patent prosecution supporting documentation and prior art + +### Business Unit Separation Pattern + +Business Unit (BU) separation leverages organizational boundaries to align with corporate structure, enabling autonomous operations while maintaining enterprise governance. + +**Architecture Rationale** + +**Organizational Alignment** +- GitHub organizations mirror corporate reporting structure +- Department/division leadership has delegated administrative control +- Independent P&L centers require cost allocation and showback +- Merger and acquisition integration with preserved autonomy +- Geographic regional separation (EMEA, APAC, Americas) + +**Autonomy vs. Governance Balance** +- **Enterprise-Level Controls**: SAML/SCIM, IP allow lists, audit log streaming, enterprise-wide policies +- **Organization-Level Autonomy**: Repository creation, team structure, internal workflows, application installations +- **Centralized Platform Team**: Shared services, reusable actions, internal packages, security tooling + +**Policy Differentiation by Business Context** + +**Example: Financial Services Conglomerate** + +| Organization | Business Context | Policy Customization | +|--------------|------------------|----------------------| +| Retail Banking | Customer-facing web/mobile | PCI DSS compliance, strict data handling | +| Investment Management | Trading algorithms | IP protection, no external collaborators | +| Insurance | Claims processing | HIPAA compliance, audit logging emphasis | +| Corporate IT | Internal tools | Standard security, relaxed policies | + +**Repository Organization Taxonomy** +- **Product-Aligned**: Separate organizations by major product lines or customer segments +- **Function-Aligned**: Engineering, Data Science, Security, Platform +- **Geography-Aligned**: Regional data residency and compliance requirements +- **Acquisition-Aligned**: Preserve acquired company structure during integration + +**Inter-Organization Collaboration Patterns** + +**Shared Code Libraries** +- **Internal Packages**: Publish reusable libraries to organization-specific GitHub Packages registry +- **Cross-Organization Access**: Grant read access to package registries via PAT or GitHub App +- **Monorepo Alternative**: Central "platform" organization hosts shared libraries + +**Reusable GitHub Actions** +- **Centralized Workflows**: Platform organization publishes enterprise-standard actions +- **Organization Workflow References**: `organization/repository/.github/workflows/workflow.yml@main` +- **Composite Actions**: Publish as releases, consumed via semantic versioning + +**Security Scanning Consolidation** +- **Central Security Organization**: Security team maintains visibility across all BU organizations +- **GitHub Advanced Security**: Enterprise-level licensing with per-organization opt-in +- **Aggregated Security Dashboard**: GitHub API + external tooling for unified vulnerability view + +**Cost Allocation and Showback** + +**Billing Separation** +- Each organization represents a cost center with independent billing reports +- GitHub Actions minutes and storage tracked per organization +- GHAS license consumption tracked via enterprise billing reports +- Export to financial systems for chargeback/showback via API integration + +**Use Cases** +- **Conglomerate Enterprises**: Multi-brand corporations with distinct business units (PepsiCo divisions, Alphabet companies) +- **Professional Services Firms**: Client-dedicated organizations with strict access boundaries +- **Holding Companies**: Portfolio companies with preserved operational independence +- **Geographic Distribution**: Regional subsidiaries with local compliance requirements +- **Merger Integration**: Phased integration strategy preserving acquired company structure + +### Compliance Separation Pattern + +Compliance separation establishes organizational boundaries to enforce regulatory requirements, contractual obligations, and industry-specific security controls. + +**Regulatory Boundary Management** + +**Isolation Requirements by Regulation** + +**PCI DSS (Payment Card Industry)** +- **In-Scope Organization**: Repositories containing payment processing logic, cardholder data handling +- **Security Controls**: Quarterly vulnerability scans, annual penetration testing, code review requirements +- **Access Restrictions**: Minimum necessary access, revocation within 24 hours of termination +- **Network Isolation**: IP allow lists restrict access to PCI network segments only +- **Audit Logging**: Enhanced logging with 1-year retention minimum + +**HIPAA (Healthcare)** +- **PHI-Handling Organization**: Repositories with Protected Health Information access +- **Security Controls**: Encryption at rest and in transit, BAA-compliant infrastructure +- **Access Control**: Role-based access, minimum necessary principle, audit trails +- **Breach Notification**: Automated alerting for unauthorized PHI access attempts +- **Data Residency**: GitHub Enterprise Cloud with Advanced Security for compliance alignment + +**FedRAMP (Federal Government)** +- **FedRAMP Organization**: Government-facing applications and systems +- **Security Controls**: Continuous monitoring, incident response, security documentation +- **Access Requirements**: Background checks, US-person restrictions, government device access +- **Data Classification**: CUI (Controlled Unclassified Information) handling procedures +- **Boundary Defense**: Strict network ingress/egress controls + +**ITAR (International Traffic in Arms Regulations)** +- **ITAR Organization**: Defense-related repositories with export-controlled technology +- **Access Control**: US person restrictions, need-to-know basis, geographic IP restrictions +- **Audit Requirements**: Detailed access logs, quarterly compliance reviews +- **Data Transfer Controls**: No repository forks to uncontrolled organizations +- **Physical Location**: Verify GitHub data residency alignment with ITAR requirements + +**Architecture Example: Healthcare Technology Company** + +```mermaid +graph TD + A[Enterprise Account] --> B[Non-Regulated Org] + A --> C[HIPAA Org] + A --> D[FedRAMP Org] + + B --> B1[Marketing Website] + B --> B2[Internal Tools] + B --> B3[Public APIs] + + C --> C1[Patient Portal] + C --> C2[EHR Integration] + C --> C3[PHI Processing] + C --> C4[BAA Required] + + D --> D1[VA System] + D --> D2[DoD Integration] + D --> D3[Continuous Monitoring] + D --> D4[US Person Only] + + style A fill:#e1f5ff + style B fill:#d4edda + style C fill:#fff3cd + style D fill:#f8d7da +``` + +**Policy Enforcement Matrix** + +| Control Domain | Non-Regulated | HIPAA | FedRAMP | +|----------------|---------------|-------|---------| +| MFA Enforcement | Required | Required + Hardware Tokens | Required + Hardware Tokens | +| IP Allow Lists | VPN Optional | Required (PHI Network) | Required (GovCloud) | +| Branch Protection | 1 Reviewer | 2 Reviewers + Security | 2 Reviewers + Security + ISSO | +| Secrets Scanning | Push Protection | Push Protection + Custom Patterns | Push Protection + Custom + Manual Review | +| Audit Retention | 90 days | 6 years | 3 years + SIEM Streaming | +| External Collaborators | Allowed | Prohibited | Prohibited | +| Third-Party Actions | Allowed | Vetted Only | Prohibited (Internal Only) | + +**Cross-Organization Data Flow Controls** + +**Data Classification Enforcement** +- **Metadata Tagging**: Repository topics indicate data classification (`data:phi`, `data:cui`, `compliance:fedramp`) +- **Automated Compliance Checks**: GitHub Actions validate no regulated data flows to non-compliant organizations +- **Code Scanning Custom Queries**: Detect potential sensitive data leaks in code + +**Shared Resource Patterns** +- **Non-Sensitive Libraries**: Reusable code promoted from non-regulated to compliant organizations after security review +- **Infrastructure-as-Code**: Network boundary definitions prevent cross-contamination +- **CI/CD Pipelines**: Separate runners and deployment targets per compliance boundary + +**Audit and Compliance Reporting** + +**Automated Compliance Evidence Collection** +- GitHub API extracts policy configurations for compliance artifacts +- Audit log streaming to SIEM for real-time compliance monitoring +- Scheduled reports: Access reviews, policy changes, security findings +- Compliance dashboard: Organization-specific compliance posture scoring + +**Use Cases** +- **Multi-Vertical Healthcare**: Hospital systems, insurance, pharmaceutical +- **Financial Services**: Investment banking, retail banking, fintech +- **Government Contractors**: Defense, intelligence, civilian agencies +- **Multi-National Corporations**: EU (GDPR), China (Cybersecurity Law), regional regulations +- **Critical Infrastructure**: Energy, utilities, telecommunications + +## Organization Naming Conventions + +Consistent naming conventions enable programmatic organization management, improve discoverability, and enforce governance through automation. + +### Naming Pattern Strategies + +**Hierarchical Prefix Naming** +``` +-- +``` + +**Examples:** +- `acme-prod-external` - Production organization for customer-facing services +- `acme-dev-platform` - Development organization for platform engineering +- `acme-sandbox-innovation` - Sandbox for R&D and experiments +- `acme-archive-legacy` - Archive for decommissioned systems +- `acme-compliance-pci` - PCI DSS compliant workloads + +**Business Unit Alignment** +``` +-- +``` + +**Examples:** +- `globex-retail-prod` - Retail division production +- `globex-insurance-dev` - Insurance division development +- `globex-corporate-it` - Corporate IT shared services + +**Geographic Distribution** +``` +-- +``` + +**Examples:** +- `initech-emea-prod` - EMEA regional production +- `initech-apac-dev` - APAC regional development +- `initech-amer-sandbox` - Americas sandbox environment + +### Naming Convention Best Practices + +**Character Constraints** +- Lowercase alphanumeric characters and hyphens only +- Maximum 39 characters (GitHub organization name limit) +- No consecutive hyphens, start/end with alphanumeric character +- Avoid ambiguous abbreviations (use `prod` not `prd`, `dev` not `dv`) + +**Semantic Clarity** +- Self-documenting names convey purpose without lookup +- Consistent terminology across enterprise (standardize on red/green or blue/green, not mixed) +- Avoid generic names (`team-a`, `org-1`) that scale poorly + +**Future-Proofing** +- Reserve naming patterns for anticipated growth (plan for 10x scale) +- Version numbers in names create migration challenges (avoid `acme-v2-prod`) +- Consider merger/acquisition scenarios (use neutral naming) + +**Automation Integration** +- Naming pattern validation via GitHub Actions workflow on organization creation +- Automated tagging based on naming pattern (e.g., `acme-prod-*` gets `environment:production` topic) +- RBAC policies derived from organization name patterns + +### Metadata and Discoverability + +**Organization Description Standard** +``` + | | | +``` + +**Example:** +``` +Customer-facing e-commerce platform | Product Engineering | Production | PCI DSS +``` + +**Organization Profile Components** +- **Email**: Organizational distribution list for notifications (`ghec-prod-admins@company.com`) +- **URL**: Link to internal documentation or runbook (`https://wiki.company.com/github/organizations/prod`) +- **Location**: Geographic region or data residency (`US-East`, `EU-West`) +- **Twitter**: Department or product Twitter handle (optional, for public organizations) + +## Migration Strategies Between Patterns + +Organizational architecture evolution requires careful planning to minimize disruption while enabling strategic transformation. + +### Migration Scenarios + +**Single to Multi-Organization Migration** + +**Trigger Conditions** +- Repository count exceeds 1,500 with discovery problems +- Security incident reveals need for blast radius reduction +- Compliance audit identifies need for regulatory separation +- Merger/acquisition requires separate organizational boundary +- Cost allocation requirements demand granular billing + +**Migration Approach: Phased Extraction** + +**Phase 1: Planning and Design (2-4 weeks)** +- Inventory all repositories, teams, and access patterns +- Define target organization structure and naming conventions +- Map repositories to target organizations based on criteria (compliance, business unit, lifecycle) +- Design team and permission model for each organization +- Document application and integration migration requirements + +**Phase 2: Pilot Migration (2-3 weeks)** +- Select low-risk pilot group (10-20 repositories, single team) +- Create target organization with policy configuration +- Transfer pilot repositories using GitHub API or UI +- Migrate team membership and configure IdP synchronization +- Validate CI/CD pipelines, GitHub Apps, and webhooks +- Document lessons learned and refine runbook + +**Phase 3: Bulk Migration (4-8 weeks)** +- Execute repository transfers in batches (50-100 repos per batch) +- Automated transfer via GitHub API with comprehensive logging +- Update documentation, links, and references +- Migrate GitHub Actions secrets and variables +- Reconfigure organization webhooks and installed applications +- Communicate changes to affected teams with migration guides + +**Phase 4: Cleanup and Optimization (2 weeks)** +- Archive or delete empty repositories in source organization +- Review and optimize team structures in new organizations +- Consolidate duplicate teams across organizations +- Validate policy enforcement and compliance posture +- Update enterprise documentation and architecture diagrams + +**Technical Considerations** + +**Repository Transfer Impacts** +- **URLs Change**: `github.com/old-org/repo` → `github.com/new-org/repo` +- **Git Remotes**: Users must update remote URLs (GitHub creates redirects for 90 days) +- **Issues/PRs**: Issue numbers preserved, but URLs change +- **Actions**: Workflow runs lose history in source organization +- **Packages**: GitHub Packages namespace changes (may require republishing) +- **Webhooks**: Organization-level webhooks require reconfiguration +- **Apps**: GitHub App installations scoped to organization require reinstallation + +**Automation Strategy** +```bash +# Example: Repository transfer via GitHub API +for repo in $(cat repos-to-migrate.txt); do + gh api \ + --method POST \ + -H "Accept: application/vnd.github+json" \ + "/repos/source-org/${repo}/transfer" \ + -f new_owner="target-org" \ + -f new_name="${repo}" + + echo "Transferred ${repo} to target-org" + sleep 2 # Rate limit consideration +done +``` + +**Multi-Organization Consolidation** + +**Trigger Conditions** +- Over-segmentation created administrative burden +- Original compliance requirement resolved (regulation changed, product decommissioned) +- Organizational restructuring merged business units +- Cost optimization initiative consolidating licenses + +**Consolidation Approach** + +**Pre-Consolidation Assessment** +- Identify policy conflicts between source organizations +- Catalog organization-specific integrations and webhooks +- Map team memberships and identify duplicates +- Assess repository name collisions in target organization +- Evaluate security and compliance implications + +**Consolidation Execution** +1. **Policy Harmonization**: Align target organization policies to most restrictive settings +2. **Team Merging**: Consolidate teams with overlapping membership +3. **Repository Transfer**: Batch transfer repositories with collision resolution (rename with prefix) +4. **Integration Migration**: Reinstall GitHub Apps and reconfigure webhooks +5. **Clean Decommission**: Delete source organizations after 30-day validation period + +**Red/Green to Single Organization** + +**Rationale**: Development velocity concerns outweigh environment separation benefits + +**Approach**: Merge Green into Red with enhanced branch protection +- Establish branch naming convention (`production/*`, `development/*`) +- Implement repository rulesets with environment-specific targeting +- Migrate deployment environment protection rules +- Consolidate CI/CD pipelines with environment-aware logic + +**Single to Red/Green/Sandbox Separation** + +**Rationale**: Security maturity progression demands defense-in-depth + +**Approach**: Extract by criticality and lifecycle +1. **Identify Production Repositories**: Customer-facing, revenue-generating, regulated +2. **Create Red Organization**: Configure maximum security posture +3. **Transfer Production Repos**: Migrate with comprehensive testing +4. **Establish Promotion Pipeline**: Define artifact promotion from Green → Red +5. **Create Sandbox**: Extract experimental repositories to separate organization + +### Migration Risk Mitigation + +**Pre-Migration Checklist** +- [ ] Backup audit logs from source organization (API export or log streaming) +- [ ] Export all repository metadata (topics, descriptions, visibility settings) +- [ ] Document all organization webhooks and installed GitHub Apps +- [ ] Capture current team structures and member access levels +- [ ] Clone critical repository wikis and GitHub Pages content +- [ ] Export organization projects and associated issues +- [ ] Validate backup strategy for rollback scenarios + +**Communication Plan** +- **T-minus 2 weeks**: Announce migration, share timeline and FAQs +- **T-minus 1 week**: Provide detailed instructions for updating git remotes +- **Migration Day**: Real-time status updates via Slack/Teams channel +- **T-plus 1 week**: Office hours for troubleshooting and support +- **T-plus 2 weeks**: Post-migration retrospective and lessons learned + +**Rollback Strategy** +- Repository transfers are reversible (transfer back to source organization) +- GitHub maintains redirects for 90 days (reduces URL change impact) +- Backup audit logs and metadata enable point-in-time restoration +- Document rollback procedure and decision criteria + +## Organization Strategy Decision Matrix + +Selecting the optimal organization architecture requires evaluating multiple dimensions against business requirements. + +### Decision Framework + +```mermaid +flowchart TD + A[Start: Evaluate Organization Strategy] --> B{Total Developers} + + B -->|< 200| C{Compliance Requirements?} + B -->|200-1000| D{Multiple Business Units?} + B -->|> 1000| E[Multi-Organization Required] + + C -->|None| F[Single Organization] + C -->|Yes| G{Regulatory Isolation?} + + G -->|No| H[Single Org + Enhanced Policies] + G -->|Yes| I[Compliance Separation Pattern] + + D -->|No| J{Prod/Dev Separation Needed?} + D -->|Yes| K[Business Unit Pattern] + + J -->|No| F + J -->|Yes| L[Red/Green Pattern] + + E --> M{Primary Driver?} + M -->|Compliance| I + M -->|Business Units| K + M -->|Environment Isolation| N[Red/Green/Sandbox Pattern] + + F --> O[+ Sandbox Org for Innovation] + H --> O + L --> O + K --> O + I --> O + N --> O + + O --> P[+ Archive Org for Retention] + P --> Q[Final Architecture] + + style F fill:#d4edda + style I fill:#fff3cd + style K fill:#d1ecf1 + style L fill:#f8d7da + style N fill:#e2e3e5 + style Q fill:#c3e6cb +``` + +### Evaluation Criteria Matrix + +| Criterion | Weight | Single Org | Red/Green | Business Unit | Compliance Separation | +|-----------|--------|------------|-----------|---------------|----------------------| +| **Team Size** | High | Optimal < 500 | Optimal < 1000 | Any | Any | +| **Admin Overhead** | Medium | Low | Medium | High | Very High | +| **Collaboration** | High | Excellent | Good | Medium | Limited | +| **Security Isolation** | High | Basic | Good | Good | Excellent | +| **Compliance** | High | Limited | Medium | Medium | Excellent | +| **Cost Allocation** | Medium | Manual | Basic | Good | Excellent | +| **Scalability** | High | Limited (< 2000 repos) | Good | Excellent | Excellent | +| **Change Velocity** | High | Fastest | Fast | Medium | Slower | + +**Scoring System** +- Assign weight to each criterion (1-5, where 5 is most critical to your organization) +- Score each pattern (1-5, where 5 is best alignment) +- Calculate weighted score: Σ(Weight × Score) +- Highest score indicates recommended pattern + +### Pattern Selection Guidelines + +**Choose Single Organization When:** +- Total developers < 300 and growth trajectory remains below 500 +- Collaboration and code sharing are paramount business requirements +- Administrative resources are limited (< 2 FTE GitHub admins) +- Compliance requirements are uniform across all development activities +- Organizational structure is flat with minimal departmental boundaries + +**Choose Red/Green Pattern When:** +- Production incidents require blast radius containment +- Regulatory compliance mandates environment separation (but not isolation) +- Different change control processes apply to production vs. development +- Development velocity is hindered by production-level controls +- Clear promotion pipeline exists for artifacts from dev to prod + +**Choose Business Unit Pattern When:** +- Multiple P&L centers require cost allocation and showback +- Departmental autonomy is critical to operational model +- Different business units have distinct compliance requirements +- Merger/acquisition integration requires preserved boundaries +- Geographic distribution necessitates regional administration + +**Choose Compliance Separation Pattern When:** +- Multiple regulatory frameworks apply (PCI + HIPAA, FedRAMP + ITAR) +- Contractual obligations require strict customer data isolation +- Audit scope reduction is critical for compliance efficiency +- Data residency requirements vary by application type +- Security clearance levels dictate access boundaries + +**Hybrid Patterns** +Most enterprises benefit from combining multiple patterns: +- **Common Architecture**: Red/Green + Sandbox + Archive +- **BU with Isolation**: Business Unit + Compliance Separation per unit +- **Geographic BU**: Business Unit (by region) + Red/Green (per BU) + +## Organization Lifecycle Management + +```mermaid +stateDiagram-v2 + [*] --> Planned: Business Case Approved + Planned --> Provisioned: Create Organization + Provisioned --> Active: Initial Setup Complete + Active --> Active: Operational Changes + Active --> Deprecated: Decommission Decision + Deprecated --> Archived: 90-Day Grace Period + Archived --> Deleted: Retention Period Complete + Deleted --> [*] + + Active --> Migrated: Org Restructure + Migrated --> Deprecated: Source Org Cleanup + + note right of Planned + - Define purpose and policies + - Request approval + - Plan naming and structure + end note + + note right of Active + - Day-to-day operations + - Policy updates + - Team management + end note + + note right of Deprecated + - Read-only access + - No new repositories + - Migration planning + end note +``` + +### Provisioning Workflow + +**Organization Request Process** +1. **Business Justification**: Requester submits organization request via internal portal or GitHub issue + - Business rationale for new organization + - Expected repository and team count + - Compliance and security requirements + - Cost center / budget approval + - Proposed naming and description + +2. **Architectural Review**: Enterprise Architect evaluates against standards + - Alignment with enterprise patterns + - Alternative solutions (team/repository vs. organization) + - Long-term scalability assessment + - Policy and compliance implications + +3. **Approval Chain**: Multi-level approval workflow + - Department head approval (business need) + - Security team approval (risk assessment) + - Enterprise Architect approval (architectural fit) + - Finance approval (budget allocation) + +4. **Automated Provisioning**: Terraform or GitHub API-based creation + ```hcl + resource "github_organization" "new_org" { + name = "acme-${var.business_unit}-${var.environment}" + description = var.org_description + billing_email = var.billing_email + + # Apply standard settings + has_organization_projects = true + has_repository_projects = true + members_can_create_repositories = false + } + ``` + +5. **Baseline Configuration**: Apply organization settings via policy-as-code + - SAML SSO configuration + - Team synchronization with IdP groups + - Repository creation policies + - GitHub Actions permissions + - Security and analysis features + - Third-party access policies + +6. **Documentation and Handoff**: Update enterprise documentation + - Add to organization inventory + - Update architecture diagrams + - Create runbook in wiki + - Notify stakeholders of new organization URL + +### Active Lifecycle Management + +**Quarterly Organization Health Check** +- **Repository Growth**: Monitor repository count vs. planned capacity +- **Team Structure**: Review team proliferation and nesting depth +- **Access Review**: Validate outside collaborators and dormant accounts +- **Policy Compliance**: Audit policy configurations against baselines +- **Cost Analysis**: Review Actions minutes, storage, and GHAS utilization +- **Security Posture**: Aggregate security alerts and response times + +**Automated Governance** +- **Policy Drift Detection**: Scheduled GitHub Actions workflow compares organization settings to baseline +- **Compliance Reporting**: Weekly reports on security findings, access anomalies, policy violations +- **Cost Alerts**: Threshold-based notifications for Actions minutes and storage consumption +- **Capacity Planning**: Trending analysis triggers expansion discussions + +### Deprecation and Decommissioning + +**Deprecation Triggers** +- Business unit restructuring or dissolution +- Technology platform migration (move to new organization architecture) +- Compliance scope change (regulation no longer applies) +- Cost optimization (consolidate underutilized organizations) +- Post-acquisition integration completion + +**Deprecation Workflow** +1. **Deprecation Notice**: Organization description updated with deprecation date +2. **Repository Freeze**: Disable repository creation, enforce read-only on non-critical repos +3. **Migration Planning**: Identify repositories requiring transfer vs. archival +4. **User Communication**: 90-day notice to organization members with transition plan +5. **Access Restriction**: Remove members with no active repositories (retain owners only) +6. **Final Migration**: Transfer remaining active repositories to target organization +7. **Archive Transfer**: Move historical repositories to Archive organization +8. **Organization Deletion**: Delete empty organization or convert to placeholder + +**Retention Considerations** +- Maintain organization for redirect purposes (GitHub redirects `old-org/repo` → `new-org/repo` for 90 days after transfer) +- Preserve audit logs via enterprise audit log streaming (organization deletion removes logs) +- Export organization metadata and team structures for historical reference + +## Cross-References + +### Related Documentation +- [Enterprise Hierarchy](01-enterprise-hierarchy.md) - Understanding the enterprise account structure that contains organizations +- [Teams and Permissions](05-teams-permissions.md) - Team structures and permission models within organizations +- [Policy Inheritance](06-policy-inheritance.md) - How enterprise policies flow down to organization level +- [Repository Governance](07-repository-governance.md) - Repository-level controls within organizational boundaries +- [Security and Compliance](08-security-compliance.md) - Security features and compliance capabilities across organizations +- [Best Practices and WAF](09-best-practices-waf.md) - Organization design best practices aligned with GitHub Well-Architected Framework + +## References + +### GitHub Documentation +- [About organizations](https://docs.github.com/en/enterprise-cloud@latest/organizations/collaborating-with-groups-in-organizations/about-organizations) +- [Managing organization settings](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings) +- [Best practices for organizations](https://docs.github.com/en/enterprise-cloud@latest/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations) +- [Transferring a repository](https://docs.github.com/en/enterprise-cloud@latest/repositories/creating-and-managing-repositories/transferring-a-repository) +- [Viewing and managing a member's SAML access](https://docs.github.com/en/enterprise-cloud@latest/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization) + +### Architecture and Best Practices +- [GitHub Enterprise Cloud Well-Architected Framework](https://wellarchitected.github.com/) +- [Enterprise account documentation](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud) +- [Establishing a GitHub enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/establishing-a-github-enterprise) +- [GitHub Enterprise onboarding resources](https://resources.github.com/learn/pathways/administration-governance/) + +### Compliance and Security +- [GitHub Enterprise Cloud security features](https://docs.github.com/en/enterprise-cloud@latest/admin/code-security) +- [About data residency](https://docs.github.com/en/enterprise-cloud@latest/admin/configuration/configuring-data-residency-for-your-enterprise) +- [GitHub compliance documentation](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud#compliance-and-security) +- [Audit log documentation](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise) + +--- + +*This document is part of the GitHub Enterprise Cloud Administration & Governance (L400) workshop series. For questions or contributions, contact the Enterprise Architecture team.* diff --git a/docs/03-identity-access-management.md b/docs/03-identity-access-management.md new file mode 100644 index 0000000..ac9df10 --- /dev/null +++ b/docs/03-identity-access-management.md @@ -0,0 +1,1386 @@ +# Identity and Access Management (IAM) + +## Overview + +Identity and Access Management (IAM) is the foundational pillar of GitHub Enterprise Cloud security and governance. This guide provides L400-level technical expertise for enterprise administrators implementing authentication, authorization, and identity lifecycle management at scale. + +GitHub Enterprise Cloud offers two distinct enterprise types with fundamentally different IAM architectures. The choice between enterprise types has far-reaching implications for authentication flows, user lifecycle management, security boundaries, and operational complexity. + +## Table of Contents + +- [Enterprise Type Selection](#enterprise-type-selection) +- [Authentication Methods Overview](#authentication-methods-overview) +- [SAML Single Sign-On (SSO) Configuration](#saml-single-sign-on-sso-configuration) +- [SCIM Provisioning Fundamentals](#scim-provisioning-fundamentals) +- [Personal Access Token (PAT) Policies](#personal-access-token-pat-policies) +- [SSH Key and GPG Key Management](#ssh-key-and-gpg-key-management) +- [Two-Factor Authentication (2FA) Enforcement](#two-factor-authentication-2fa-enforcement) +- [Advanced IAM Considerations](#advanced-iam-considerations) +- [References](#references) + +--- + +## Enterprise Type Selection + +### Enterprise Types Comparison + +GitHub Enterprise Cloud offers two mutually exclusive enterprise architectures: + +| Aspect | Enterprise with Personal Accounts | Enterprise with Managed Users (EMU) | +|--------|-----------------------------------|-------------------------------------| +| **Identity Ownership** | User-controlled personal accounts | Enterprise-controlled managed accounts | +| **Authentication** | Optional SAML SSO per organization | Mandatory SAML/OIDC SSO at enterprise level | +| **User Provisioning** | Manual or org-level SCIM | Enterprise-level SCIM with full lifecycle | +| **Username Control** | User-defined | IdP-normalized (e.g., `user_shortcode`) | +| **Profile Management** | User-controlled | IdP-controlled (immutable on GitHub) | +| **External Collaboration** | Native support | Requires separate personal account | +| **Public Content** | Allowed | Prohibited (no public repos/gists/Pages) | +| **Migration Path** | Bidirectional between orgs | Requires new enterprise (no in-place upgrade) | +| **Data Residency** | Not available | Required for data residency compliance | +| **Recovery Access** | User password reset | Setup user (`SHORTCODE_admin`) | +| **Audit Granularity** | Org-level with external identity links | Enterprise-level with complete IdP control | + +### Decision Framework + +```mermaid +flowchart TD + Start([IAM Architecture Decision]) --> Q1{Need complete
identity control?} + + Q1 -->|Yes| Q2{IdP as source
of truth?} + Q1 -->|No| PersonalAccounts[Enterprise with
Personal Accounts] + + Q2 -->|Yes| Q3{Supported
partner IdP?} + Q2 -->|No| PersonalAccounts + + Q3 -->|Yes| Q4{Data residency
required?} + Q3 -->|No| Q5{API-based SCIM
acceptable?} + + Q4 -->|Yes| EMU_Required[EMU Required
with Data Residency] + Q4 -->|No| Q6{External collab
minimal?} + + Q5 -->|Yes| Q7{External collab
minimal?} + Q5 -->|No| PersonalAccounts + + Q6 -->|Yes| Q8{Public content
not needed?} + Q6 -->|No| HybridModel[Hybrid: EMU +
Personal Accounts] + + Q7 -->|Yes| Q9{Public content
not needed?} + Q7 -->|No| HybridModel + + Q8 -->|Yes| Q10{Migration cost
acceptable?} + Q8 -->|No| PersonalAccounts + + Q9 -->|Yes| Q11{Migration cost
acceptable?} + Q9 -->|No| PersonalAccounts + + Q10 -->|Yes| EMU[Enterprise Managed
Users EMU] + Q10 -->|No| PersonalAccounts + + Q11 -->|Yes| EMU + Q11 -->|No| PersonalAccounts + + EMU_Required --> PartnerIdP{Using partner IdP?} + EMU --> PartnerIdP + + PartnerIdP -->|Entra ID| EntraSetup[Entra ID SAML/OIDC
+ SCIM via App] + PartnerIdP -->|Okta| OktaSetup[Okta SAML/OIDC
+ SCIM via App] + PartnerIdP -->|PingFederate| PingSetup[PingFederate
via REST API] + PartnerIdP -->|Other| APISetup[Custom SCIM
via REST API] + + PersonalAccounts --> OrgSAML[Org-level SAML SSO
Optional SCIM] + + style EMU fill:#e1f5e1 + style EMU_Required fill:#e1f5e1 + style PersonalAccounts fill:#e1f0ff + style HybridModel fill:#fff4e1 +``` + +### Enterprise with Personal Accounts + +**Architecture Characteristics:** +- Users authenticate with GitHub-managed personal accounts +- Optional SAML SSO configured per organization (not enterprise-wide) +- Users may belong to multiple enterprises with single account +- SCIM provisioning only manages organization membership, not accounts +- Users retain full control over username, profile, and personal repositories + +**Ideal Use Cases:** +- Organizations with established GitHub user base +- Environments requiring extensive external collaboration +- Teams needing public repository and GitHub Pages access +- Enterprises not ready for comprehensive IdP integration +- Multi-enterprise users (contractors, open-source maintainers) + +**Implementation Considerations:** +- Configure SAML SSO independently for each organization +- Enforce SAML authentication via organization security settings +- Link external identities using SAML NameID assertion +- Manage access via GitHub teams synchronized with IdP groups (optional) +- Monitor external collaborator access patterns + +### Enterprise Managed Users (EMU) + +**Architecture Characteristics:** +- Complete identity lifecycle managed from IdP (provision, update, deprovision) +- Mandatory SAML/OIDC authentication at enterprise boundary +- Username format: `{idp_username}_{shortcode}` (e.g., `jsmith_acme`) +- Profile data (name, email) immutable on GitHub, controlled by IdP +- Strong isolation: managed users cannot access content outside enterprise +- Setup user account for emergency access: `{shortcode}_admin` + +**Ideal Use Cases:** +- Enterprises requiring true SSO with centralized identity governance +- Organizations with security compliance mandates (SOC 2, ISO 27001) +- Environments prohibiting public content creation +- Companies needing data residency capabilities +- Strict deprovisioning requirements for terminated employees + +**Implementation Considerations:** +- **Cannot be applied to existing enterprises** - requires new enterprise creation +- Setup user credentials must be securely stored for recovery scenarios +- Users requiring external collaboration need separate personal accounts +- IdP must support SAML 2.0 or OIDC 1.0 + SCIM 2.0 specifications +- Plan for username normalization conflicts (IdP identifier collisions) + +### Supported Identity Providers + +#### Partner IdPs (Paved-Path Integration) + +**Microsoft Entra ID (Azure AD):** +- SAML 2.0 or OIDC support with Conditional Access Policy (CAP) validation +- Enterprise application with automated SCIM provisioning +- Group-based role assignment and team synchronization +- Limitation: Does not support nested group provisioning + +**Okta:** +- SAML 2.0 or OIDC authentication +- Native GitHub EMU application with SCIM provisioning +- Support for group push and role assignment +- Extensive attribute mapping capabilities + +**PingFederate:** +- SAML 2.0 authentication (partner support) +- SCIM provisioning via REST API (not native application) +- Requires manual configuration of SCIM endpoints + +**Critical Restriction:** +> ⚠️ **Mixing Okta and Entra ID for SSO and SCIM (in either direction) is explicitly unsupported.** GitHub's SCIM API returns errors when this combination is detected. Choose one partner IdP for both authentication and provisioning. + +#### Non-Partner IdPs + +Any IdP meeting these requirements: +- SAML 2.0 specification compliance for authentication +- SCIM 2.0 specification compliance for provisioning +- REST API integration for user lifecycle management +- GitHub integration guidelines adherence + +**Support Limitations:** +- GitHub Support may not assist with custom/mixed IdP configurations +- Extensive testing and validation required +- Documentation and troubleshooting responsibility falls on enterprise + +--- + +## Authentication Methods Overview + +### Authentication Architecture + +```mermaid +sequenceDiagram + participant User + participant Browser + participant GitHub + participant IdP + participant SCIM + + Note over User,SCIM: Initial Provisioning (EMU) + SCIM->>GitHub: POST /scim/v2/Users + GitHub->>SCIM: 201 Created (user_shortcode) + + Note over User,IdP: Authentication Flow + User->>Browser: Navigate to github.com/enterprises/ENTERPRISE + Browser->>GitHub: Request resource + GitHub->>Browser: 302 Redirect to IdP (SAML/OIDC) + Browser->>IdP: SAML AuthnRequest / OIDC Authorization Request + + alt SAML Authentication + IdP->>User: Present login page + User->>IdP: Provide credentials + MFA + IdP->>IdP: Validate credentials & CAP + IdP->>Browser: SAML Response (signed assertion) + Browser->>GitHub: POST /saml/consume + GitHub->>GitHub: Validate signature & assertions + GitHub->>Browser: Set session cookie + else OIDC Authentication + IdP->>User: Present login page + User->>IdP: Provide credentials + MFA + IdP->>IdP: Validate credentials & CAP + IdP->>Browser: Authorization Code + Browser->>GitHub: Authorization Code + GitHub->>IdP: Token Exchange + IdP->>GitHub: ID Token + Access Token + GitHub->>GitHub: Validate tokens & claims + GitHub->>Browser: Set session cookie + end + + Browser->>GitHub: Access resource with session + GitHub->>User: Grant access + + Note over User,SCIM: Deprovisioning + SCIM->>GitHub: PATCH /scim/v2/Users/{id} (active=false) + GitHub->>SCIM: 200 OK + GitHub->>GitHub: Invalidate sessions +``` + +### Authentication Methods by Enterprise Type + +#### Personal Accounts Enterprise + +1. **Username/Password:** Native GitHub authentication (always available) +2. **SAML SSO (Optional):** Per-organization SAML 2.0 authentication +3. **OAuth Apps:** Third-party application authorization +4. **GitHub Mobile:** Mobile device authentication with push notifications +5. **Two-Factor Authentication:** TOTP, SMS, or security keys (optional/required per org) + +#### EMU Enterprise + +1. **SAML 2.0 SSO (Mandatory):** Enterprise-wide SAML authentication with IdP +2. **OIDC 1.0 SSO (Mandatory):** OpenID Connect with CAP support (Entra ID) +3. **Setup User:** Emergency access via `{shortcode}_admin` account +4. **Personal Access Tokens:** Fine-grained or classic tokens (policy-controlled) +5. **SSH Keys:** Git protocol authentication (IdP identity-linked) + +### Session Management + +**Session Duration:** +- SAML SSO: Configurable in IdP (typically 8-24 hours) +- OIDC SSO: Controlled by token lifetime and refresh policies +- GitHub session: Maximum 90 days (refreshed on activity) + +**Session Invalidation:** +- User logout from GitHub +- IdP-initiated logout (SAML SLO - Single Logout) +- Account deprovisioning via SCIM +- Password change or credential revocation +- Security policy enforcement (IP whitelist violation) + +--- + +## SAML Single Sign-On (SSO) Configuration + +### SAML 2.0 Protocol Overview + +SAML (Security Assertion Markup Language) enables federated authentication by allowing GitHub to trust identity assertions from external IdPs. The protocol uses XML-based messages exchanged via HTTP redirects/POSTs. + +### IdP Setup: Microsoft Entra ID + +#### Prerequisites +- Azure AD Premium P1/P2 license (for CAP support with OIDC) +- Global Administrator or Application Administrator role +- GitHub Enterprise Cloud with EMU (for enterprise-level SSO) + +#### Configuration Steps + +**1. Create Enterprise Application** +```bash +# Azure CLI approach (alternative to portal) +az ad app create \ + --display-name "GitHub EMU - ACME Corp" \ + --sign-in-audience AzureADMyOrg \ + --required-resource-accesses @manifest.json +``` + +**2. Configure Single Sign-On** + +Navigate to Azure Portal → Enterprise Applications → GitHub EMU → Single sign-on: + +- **SSO Method:** SAML or OIDC +- **Entity ID:** `https://github.com/enterprises/{ENTERPRISE_SLUG}` +- **Reply URL (ACS):** `https://github.com/enterprises/{ENTERPRISE_SLUG}/saml/consume` +- **Sign-on URL:** `https://github.com/enterprises/{ENTERPRISE_SLUG}/sso` +- **Logout URL:** `https://github.com/enterprises/{ENTERPRISE_SLUG}/saml/slo` + +**3. Download Metadata** + +Export SAML metadata XML or note these values: +- **IdP SSO URL:** `https://login.microsoftonline.com/{tenant}/saml2` +- **IdP Issuer:** `https://sts.windows.net/{tenant}/` +- **X.509 Certificate:** Base64-encoded public certificate + +#### SAML Attribute Mapping + +Critical SAML assertions for GitHub EMU: + +| GitHub Attribute | SAML Assertion | Entra ID Source | Required | +|------------------|----------------|-----------------|----------| +| `NameID` | Subject NameID | `user.userprincipalname` or `user.mail` | Yes | +| `administrator` | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/administrator` | Custom (group membership) | No | +| `userName` | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | `user.userprincipalname` | Yes | +| `emails` | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail` | Yes | +| `firstName` | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | `user.givenname` | Yes | +| `lastName` | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | `user.surname` | Yes | + +**Advanced: Role-Based Attribute** + +Configure administrator role via group claim: +```xml + + + + Join("", + If( + Contains([group], "github-enterprise-owners-guid"), + "true", + "false" + ) + ) + + +``` + +#### Conditional Access Policy (CAP) Integration + +For OIDC authentication, configure CAP to enforce: +- **Multi-Factor Authentication:** Require MFA for GitHub access +- **Device Compliance:** Restrict to Intune-managed devices +- **Location Restrictions:** Block access from unapproved countries +- **Risk-Based Policies:** Require step-up auth for risky sign-ins + +GitHub validates CAP enforcement during OIDC token exchange. + +### IdP Setup: Okta + +#### Prerequisites +- Okta Workforce Identity or Customer Identity Cloud +- Organization Administrator or Application Administrator role +- GitHub EMU enterprise shortcode + +#### Configuration Steps + +**1. Add GitHub EMU Application** + +Okta Admin Console → Applications → Browse App Catalog → "GitHub Enterprise Managed User" + +**2. Configure Application Settings** + +- **GitHub Enterprise Slug:** `{ENTERPRISE_SLUG}` +- **GitHub Enterprise Shortcode:** `{SHORTCODE}` +- **SCIM Provisioning:** Enable (requires API token from GitHub) + +**3. SAML Settings (Automatic via Template)** + +Pre-configured by Okta application: +- **SSO URL:** Auto-populated +- **Audience URI:** Auto-populated +- **Name ID Format:** EmailAddress +- **Application Username:** Okta username prefix + +**4. Attribute Mapping** + +| Okta User Attribute | GitHub SAML Attribute | +|---------------------|-----------------------| +| `user.login` | `userName` | +| `user.email` | `emails` | +| `user.firstName` | `firstName` | +| `user.lastName` | `lastName` | +| Group membership | `roles` (via API) | + +**5. Group-Based Roles** + +Use Okta groups to assign GitHub enterprise roles: +- Create rule: If user is member of `github-owners` → Set `roles=enterprise_owner` +- Okta sends role information during provisioning API calls + +### IdP Setup: PingFederate + +#### Configuration Steps + +**1. Create SP Connection** + +PingFederate Admin → SP Connections → Create New: +- **Partner Entity ID:** `https://github.com/enterprises/{ENTERPRISE_SLUG}` +- **Connection Type:** Browser SSO +- **Binding:** HTTP POST or HTTP Redirect + +**2. Configure SSO Service URLs** + +- **Assertion Consumer Service (ACS):** + - URL: `https://github.com/enterprises/{ENTERPRISE_SLUG}/saml/consume` + - Binding: HTTP POST + - Index: 0 (default) + +**3. Attribute Contract** + +Define attributes passed to GitHub: +- **Subject NameID:** Persistent identifier (email or username) +- **userName:** User's unique identifier +- **emails:** User's email address +- **firstName, lastName:** User's display name components + +**4. Signature Policy** + +- Sign assertion: Enabled +- Sign response: Enabled (recommended) +- Algorithm: RSA-SHA256 or RSA-SHA512 +- Certificate: Valid X.509 certificate from trusted CA + +### GitHub Enterprise Configuration + +#### Enable SAML SSO + +**For EMU Enterprise:** + +1. Sign in as setup user: `{SHORTCODE}_admin` +2. Navigate to Enterprise → Settings → Authentication security +3. Select "Enable SAML authentication" +4. Upload IdP metadata XML or enter manually: + - **Sign-on URL:** IdP SAML SSO endpoint + - **Issuer:** IdP entity ID + - **Public Certificate:** X.509 certificate (PEM format) +5. Configure NameID format: Email Address (recommended) +6. Test SSO with setup user session active (new private window) +7. Enable "Require SAML authentication" after successful test + +**Verification Steps:** +```bash +# Test SAML metadata endpoint +curl -I https://github.com/enterprises/{ENTERPRISE}/saml/metadata + +# Verify certificate expiration +openssl x509 -in idp_certificate.pem -noout -enddate + +# Test SSO flow +curl -v https://github.com/enterprises/{ENTERPRISE}/sso \ + --user-agent "Mozilla/5.0" +``` + +#### SSO Enforcement and Recovery + +**Enforcement Levels:** + +1. **Recommended (Soft Enforcement):** + - Display SSO banner for unauthenticated users + - Allow personal account access for setup user + - Graceful degradation for troubleshooting + +2. **Required (Hard Enforcement):** + - Redirect all unauthenticated requests to IdP + - Block access without valid SAML assertion + - Setup user exempt for emergency access + +**Recovery Procedures:** + +**Scenario 1: IdP Outage** +```bash +# Emergency access via setup user +# 1. Navigate to https://github.com/enterprises/{ENTERPRISE}/settings/security +# 2. Sign in as {SHORTCODE}_admin +# 3. Temporarily disable "Require SAML authentication" +# 4. Users can authenticate with GitHub credentials +# 5. Re-enable after IdP restoration +``` + +**Scenario 2: Certificate Expiration** +```bash +# Urgent certificate rotation +# 1. Generate new certificate on IdP +# 2. Sign in to GitHub as setup user +# 3. Enterprise → Authentication security → Edit SAML +# 4. Upload new certificate (old cert still valid during overlap) +# 5. Test authentication with new cert +# 6. Revoke old certificate on IdP +``` + +**Scenario 3: Misconfigured Attributes** +```bash +# Debug SAML assertions +# 1. Enable SAML debug mode (contact GitHub Support) +# 2. Authenticate as test user +# 3. Review SAML assertion in audit log: +# Enterprise → Settings → Audit log → Filter: "saml" +# 4. Identify missing/malformed attributes +# 5. Correct attribute mapping on IdP +# 6. Test with same user +``` + +#### SSO for Unauthenticated Users + +**Configuration Options:** + +- **Redirect Unauthenticated Users:** Automatically send to IdP (recommended for EMU) +- **Display 404 Error:** Require explicit SSO URL navigation (default for privacy) + +**Implementation:** +```bash +# Enterprise Settings → Security → Authentication +# Enable: "Automatically redirect unauthenticated users to SSO" +``` + +**Use Cases:** +- **Enable:** Seamless user experience, no confusion about authentication method +- **Disable:** Privacy-conscious organizations hiding enterprise existence from scanners + +--- + +## SCIM Provisioning Fundamentals + +### SCIM 2.0 Protocol Overview + +System for Cross-domain Identity Management (SCIM) standardizes user and group provisioning via RESTful APIs. GitHub implements SCIM 2.0 RFC 7644 for EMU user lifecycle management. + +### SCIM User Lifecycle + +```mermaid +stateDiagram-v2 + [*] --> Unprovisioned: User created in IdP + Unprovisioned --> Provisioned: POST /scim/v2/Users + Provisioned --> Active: User assigned to GitHub app + Active --> Suspended: PATCH active=false + Suspended --> Active: PATCH active=true + Active --> Updated: PATCH user attributes + Updated --> Active: Changes applied + Active --> Deprovisioned: DELETE /scim/v2/Users/{id} + Suspended --> Deprovisioned: DELETE /scim/v2/Users/{id} + Deprovisioned --> [*]: Username hashed + + note right of Provisioned + User account created + Username: user_shortcode + No enterprise access yet + end note + + note right of Active + Active enterprise member + Org access via groups + Can authenticate via SSO + end note + + note right of Suspended + Sessions invalidated + Username: hash_shortcode + Account data retained + end note + + note right of Deprovisioned + Permanent deactivation + Username changed to hash + Contributions preserved + end note +``` + +### SCIM Provisioning Configuration + +#### Partner IdP: Microsoft Entra ID + +**1. Enable Provisioning in Enterprise App** + +Azure Portal → Enterprise Applications → GitHub EMU → Provisioning: +- **Provisioning Mode:** Automatic +- **Tenant URL:** `https://api.github.com/scim/v2/enterprises/{ENTERPRISE}` +- **Secret Token:** Generate from GitHub (Enterprise → Settings → Security) +- **Notification Email:** Email for provisioning error alerts + +**2. Attribute Mapping** + +Azure AD → GitHub EMU → Provisioning → Mappings → "Provision Azure AD Users": + +| Azure AD Attribute | GitHub Attribute | Notes | +|--------------------|------------------|-------| +| `userPrincipalName` | `userName` | Normalized to lowercase, special chars removed | +| `mail` | `emails[type eq "work"].value` | Primary email address | +| `givenName` | `name.givenName` | First name | +| `surname` | `name.familyName` | Last name | +| `displayName` | `displayName` | Full display name | +| `accountEnabled` | `active` | `true` = active, `false` = suspended | +| `externalId` | `externalId` | Azure AD object ID (immutable) | + +**3. Group Provisioning (Team Synchronization)** + +Azure AD → GitHub EMU → Provisioning → Mappings → "Provision Azure AD Groups": + +| Azure AD Attribute | GitHub Attribute | Notes | +|--------------------|------------------|-------| +| `displayName` | `displayName` | Group/team name on GitHub | +| `members` | `members` | Group membership synchronization | +| `mailNickname` | `externalId` | Unique group identifier | + +**Configuration:** +- Enable group provisioning in provisioning settings +- Assign Azure AD groups to GitHub EMU application +- Map groups to GitHub teams via IdP groups feature + +**4. Scoping Filters** + +Define which users to provision: +```bash +# Example: Only provision users with specific attribute +# Azure AD → Provisioning → Mappings → Scope +- Filter: extensionAttribute1 Equals "github_user" +- Filter: department Equals "Engineering" OR department Equals "Product" +``` + +**5. Start Provisioning** + +- **Initial Sync:** Provisions all in-scope users/groups (can take minutes to hours) +- **Incremental Sync:** Runs every 40 minutes (Entra ID default) +- **On-Demand Sync:** Manually trigger for specific user + +#### Partner IdP: Okta + +**1. Configure SCIM in Okta Application** + +Okta Admin → Applications → GitHub EMU → Provisioning: +- **Enable:** Provisioning to App +- **SCIM Base URL:** Auto-configured +- **API Token:** Paste token from GitHub enterprise settings + +**2. Provisioning Features** + +Enable: +- **Create Users:** Provision new managed user accounts +- **Update User Attributes:** Sync profile changes (name, email) +- **Deactivate Users:** Suspend accounts when unassigned +- **Group Push:** Sync Okta groups to GitHub teams + +**3. Attribute Mapping** + +Okta → GitHub EMU → Provisioning → Attribute Mappings: + +| Okta Attribute | GitHub Attribute | +|----------------|------------------| +| `login` | `userName` | +| `email` | `emails.value` | +| `firstName` | `name.givenName` | +| `lastName` | `name.familyName` | + +**4. Group Push Configuration** + +Okta Admin → Directory → Groups → {Group} → Applications → GitHub EMU: +- **Push Status:** Active +- **Push Group Memberships:** Immediately or on schedule +- Creates corresponding team in GitHub organization (specified via API) + +#### Non-Partner IdPs: REST API Provisioning + +**1. Generate SCIM Token** + +GitHub Enterprise → Settings → Security → Personal access tokens → Enable Open SCIM: +- Sign in as `{SHORTCODE}_admin` +- Navigate to Identity provider → Single sign-on configuration +- Enable "Open SCIM configuration" +- Generate token (store securely - shown once) + +**2. SCIM API Endpoints** + +Base URL: `https://api.github.com/scim/v2/enterprises/{ENTERPRISE}` + +**User Provisioning:** +```bash +# Create user +POST /scim/v2/enterprises/{ENTERPRISE}/Users +Content-Type: application/scim+json +Authorization: Bearer {SCIM_TOKEN} + +{ + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "jsmith", + "name": { + "givenName": "Jane", + "familyName": "Smith" + }, + "emails": [{ + "value": "jsmith@example.com", + "type": "work", + "primary": true + }], + "active": true, + "externalId": "idp-user-12345" +} + +# Response: 201 Created +{ + "id": "github-user-guid", + "userName": "jsmith_shortcode", + "active": true, + ... +} +``` + +**Update User:** +```bash +PATCH /scim/v2/enterprises/{ENTERPRISE}/Users/{id} +Content-Type: application/scim+json + +{ + "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], + "Operations": [{ + "op": "replace", + "path": "name.givenName", + "value": "Janet" + }] +} +``` + +**Deactivate User:** +```bash +PATCH /scim/v2/enterprises/{ENTERPRISE}/Users/{id} + +{ + "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], + "Operations": [{ + "op": "replace", + "path": "active", + "value": false + }] +} +``` + +**3. Group Provisioning:** +```bash +# Create group +POST /scim/v2/enterprises/{ENTERPRISE}/Groups + +{ + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "Engineering Team", + "externalId": "idp-group-67890", + "members": [ + { + "value": "github-user-guid-1", + "$ref": "https://api.github.com/scim/v2/enterprises/{ENTERPRISE}/Users/github-user-guid-1" + } + ] +} + +# Add member to group +PATCH /scim/v2/enterprises/{ENTERPRISE}/Groups/{id} + +{ + "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], + "Operations": [{ + "op": "add", + "path": "members", + "value": [{ + "value": "github-user-guid-2" + }] + }] +} +``` + +### Automated User Lifecycle Management + +#### Provisioning Workflows + +**New Employee Onboarding:** +1. HR system creates user in IdP +2. User assigned to GitHub EMU application/group +3. IdP sends SCIM POST request to GitHub +4. GitHub creates managed user account: `{username}_{shortcode}` +5. IdP assigns groups → GitHub teams provisioned/updated +6. User receives welcome email (if configured) +7. User authenticates via SSO → gains access to assigned repositories + +**User Attribute Updates:** +1. User profile changed in IdP (name, email) +2. IdP detects change (delta sync or polling) +3. IdP sends SCIM PATCH request to GitHub +4. GitHub updates user profile immediately +5. Changes reflected in user's GitHub profile, commits, etc. + +**Employee Termination:** +1. HR system deactivates user in IdP +2. IdP unassigns user from GitHub application +3. IdP sends SCIM PATCH with `active: false` or DELETE request +4. GitHub immediately: + - Invalidates all active sessions + - Disables account access + - Changes username to hash: `{hash}_{shortcode}` + - Retains contribution history and authored content +5. User cannot authenticate via SSO +6. Account can be reactivated if termination reversed + +#### Group Synchronization + +**Team Membership Management:** + +GitHub supports IdP group → GitHub team synchronization: +- **IdP Groups:** Define in identity provider (Azure AD, Okta, etc.) +- **GitHub Teams:** Organizational units for repository access control +- **Synchronization:** Automatic via SCIM group provisioning + +**Configuration:** +```bash +# 1. Create IdP group (e.g., "github-platform-engineering") +# 2. Assign users to IdP group +# 3. Push group to GitHub (Okta) or assign to app (Entra ID) +# 4. GitHub creates/updates team in specified organization +# 5. Team members inherit repository permissions +``` + +**Mapping Strategy:** +- **One-to-One:** Each IdP group maps to one GitHub team +- **Hierarchical:** Nested IdP groups (Okta) → parent/child teams +- **Cross-Organization:** Same IdP group provisions teams in multiple orgs + +**Example: Organization Assignment via Group:** +```bash +# IdP group metadata (sent to GitHub) +{ + "displayName": "Engineering-Backend", + "externalId": "idp-group-backend-eng", + "members": [...] +} + +# GitHub team creation (automatic) +# Organization: acme-corp +# Team: backend-engineers +# Members: Synced from IdP group +# Repositories: Assigned via GitHub team settings +``` + +#### Deprovisioning Workflows + +**Graceful Deprovisioning:** +1. Deprovision user from GitHub EMU application in IdP +2. GitHub marks account as inactive (`active: false`) +3. Username changed to hash to free original for reuse +4. Contributions preserved under hashed username +5. User's commits, issues, PRs remain attributed to hashed account +6. Reactivation possible by reassigning to application + +**Immediate Revocation:** +1. Delete user via SCIM DELETE endpoint +2. All sessions terminated immediately +3. Account permanently disabled +4. No reactivation path without reprovisioning + +**Best Practices:** +- **Soft Delete:** Use `active: false` for temporary terminations (leave, suspension) +- **Hard Delete:** Use DELETE for permanent departures +- **Audit Retention:** Maintain deprovisioned user records for compliance +- **Automated Workflows:** Trigger deprovisioning from HR system (Workday, BambooHR) + +--- + +## Personal Access Token (PAT) Policies + +### Token Types + +**1. Fine-Grained Personal Access Tokens (Beta)** +- Granular repository and permission scope +- Expiration required (1-365 days, or custom) +- Organization-level approval workflow +- API access to specific repositories only + +**2. Classic Personal Access Tokens** +- Broad permission scopes (repo, admin, workflow) +- Optional expiration +- No organization approval by default +- Legacy support for existing integrations + +### PAT Policy Configuration + +**Enterprise-Level Policies:** + +GitHub Enterprise → Settings → Personal access tokens: + +**1. Restrict Classic PAT Creation:** +- **Allow:** Members can create classic PATs (default) +- **Restrict:** Block classic PAT creation enterprise-wide +- **Approval Required:** Admins approve classic PAT requests + +**2. Fine-Grained PAT Requirements:** +- **Require Expiration:** Enforce maximum token lifetime (e.g., 90 days) +- **Require Approval:** Organization owners approve fine-grained PATs +- **Allowed Repositories:** Limit to specific repository patterns + +**3. Token Rotation Policies:** +- Enforce token regeneration every N days +- Email notifications for expiring tokens +- Automated revocation of expired tokens + +**Example Policy:** +```yaml +# Enterprise PAT policy (conceptual YAML) +classic_tokens: + enabled: false # Disable classic PATs + +fine_grained_tokens: + enabled: true + require_approval: true + max_lifetime_days: 90 + allowed_permissions: + - contents: read + - pull_requests: write + - workflows: write # Restricted to admins only + +rotation_policy: + enforce_rotation_days: 60 + notification_days_before_expiry: 14 +``` + +### Token Security Best Practices + +**1. Secure Storage:** +- Store tokens in secret management systems (HashiCorp Vault, Azure Key Vault) +- Never commit tokens to repositories (use secret scanning) +- Rotate tokens stored in CI/CD systems quarterly + +**2. Least Privilege:** +- Grant minimum required permissions for token purpose +- Use fine-grained tokens over classic tokens +- Separate tokens for different use cases (CI, API access, CLI) + +**3. Monitoring and Auditing:** +- Review PAT usage in audit log: Enterprise → Audit log → Filter: "oauth_access" +- Alert on suspicious token usage (unusual IP, geographic anomaly) +- Revoke unused tokens after 90 days of inactivity + +**4. Token Authentication in CI/CD:** +```bash +# GitHub Actions: Use GITHUB_TOKEN (automatic, scoped) +- name: Checkout code + uses: actions/checkout@v3 + with: + token: ${{ secrets.GITHUB_TOKEN }} # Preferred + +# GitHub Actions: Use PAT for cross-repo access +- name: Access external repo + env: + GH_TOKEN: ${{ secrets.FINE_GRAINED_PAT }} + run: gh repo clone external-org/repo +``` + +--- + +## SSH Key and GPG Key Management + +### SSH Key Management + +**Key Types and Support:** +- **RSA:** 2048-bit minimum, 4096-bit recommended +- **Ed25519:** Preferred (smaller, faster, more secure) +- **ECDSA:** P-256, P-384, P-521 curves supported +- **DSA:** Deprecated (insecure, unsupported) + +**SSH Key Policies:** + +**1. Enterprise SSH Key Requirements:** +```bash +# Enforce SSH certificate authority (advanced) +# Enterprise → Settings → SSH certificate authorities +# Upload CA public key for signed SSH certificates +``` + +**2. User SSH Key Management:** + +For EMU users: +- SSH keys linked to managed user identity +- Keys uploaded to `https://github.com/settings/keys` +- Keys verified via SAML/OIDC assertion (user must be authenticated) + +```bash +# Generate Ed25519 key (recommended) +ssh-keygen -t ed25519 -C "jsmith@example.com" + +# Add to SSH agent +eval "$(ssh-agent -s)" +ssh-add ~/.ssh/id_ed25519 + +# Add public key to GitHub +# Copy public key: cat ~/.ssh/id_ed25519.pub +# GitHub → Settings → SSH and GPG keys → New SSH key +``` + +**3. SSH Key Rotation:** +```bash +# Best practice: Rotate SSH keys annually +# 1. Generate new key pair +# 2. Add new public key to GitHub +# 3. Test new key +# 4. Remove old key from GitHub +# 5. Delete old private key +``` + +**4. SSH Certificate Authority (Advanced):** + +For enterprises requiring SSH certificate-based authentication: +```bash +# 1. Generate CA key pair +ssh-keygen -t rsa -b 4096 -f github-ssh-ca + +# 2. Sign user's public key with CA +ssh-keygen -s github-ssh-ca \ + -I jsmith@example.com \ + -n git \ + -V +52w \ + ~/.ssh/id_ed25519.pub + +# 3. Upload CA public key to GitHub Enterprise +# 4. Users present signed certificates for git operations +``` + +### GPG Key Management + +**GPG Key for Commit Signing:** + +**1. Generate GPG Key:** +```bash +# Generate 4096-bit RSA key +gpg --full-generate-key +# Select: (1) RSA and RSA +# Keysize: 4096 +# Expiration: 2y (2 years recommended) +# User ID: Name and email matching GitHub + +# List keys +gpg --list-secret-keys --keyid-format=long + +# Export public key +gpg --armor --export {KEY_ID} +``` + +**2. Add GPG Key to GitHub:** +```bash +# Copy GPG public key block +gpg --armor --export {KEY_ID} | pbcopy + +# GitHub → Settings → SSH and GPG keys → New GPG key +# Paste public key +``` + +**3. Configure Git for Signing:** +```bash +# Set signing key +git config --global user.signingkey {KEY_ID} + +# Enable commit signing by default +git config --global commit.gpgsign true + +# Enable tag signing +git config --global tag.gpgSign true +``` + +**4. Verify Signed Commits:** +```bash +# Sign a commit +git commit -S -m "Signed commit" + +# Verify signature +git log --show-signature + +# GitHub displays "Verified" badge for signed commits +``` + +**5. Enterprise GPG Policies:** + +Enforce commit signing at organization level: +```bash +# Organization → Settings → Repository defaults +# Enable: "Require contributors to sign off on web-based commits" + +# Branch protection rules +# Enable: "Require signed commits" +# Blocks pushes with unsigned commits +``` + +--- + +## Two-Factor Authentication (2FA) Enforcement + +### 2FA Methods + +**Supported 2FA Methods:** + +1. **TOTP (Time-based One-Time Password):** + - Authenticator apps: Google Authenticator, Microsoft Authenticator, Authy + - 6-digit codes rotating every 30 seconds + - Recommended primary method + +2. **SMS (Text Message):** + - Backup method (less secure than TOTP) + - Subject to SIM swapping attacks + - Not recommended as primary method + +3. **Security Keys (WebAuthn/U2F):** + - Hardware tokens: YubiKey, Titan Security Key, Feitian + - Strongest 2FA method (phishing-resistant) + - Supports passkeys (FIDO2) + - Recommended for high-privilege accounts + +4. **GitHub Mobile:** + - Push notification approval on mobile app + - Biometric authentication on device + - Convenient for frequent authentications + +5. **Recovery Codes:** + - One-time use codes for 2FA recovery + - Store securely (password manager, secure note) + - Generate new codes after use + +### Enterprise 2FA Enforcement + +**Organization-Level Enforcement:** + +For enterprises with personal accounts: +```bash +# Organization → Settings → Authentication security +# Enable: "Require two-factor authentication" +# Members without 2FA: 7-day grace period to enable or removed from org +``` + +**Enterprise-Level Enforcement (EMU):** + +For EMU enterprises, 2FA enforced at IdP level: +- IdP MFA policies control GitHub access +- GitHub trusts IdP's authentication assertion +- Configure MFA in IdP (Entra ID Conditional Access, Okta MFA) + +**Implementation Strategy:** + +**Phase 1: Communication (Week 1-2)** +- Announce 2FA enforcement timeline +- Provide documentation and tutorials +- Offer office hours for assistance + +**Phase 2: Monitoring (Week 3-4)** +- Identify members without 2FA enabled +- Send targeted reminders +- Provide 1:1 support for struggling users + +**Phase 3: Enforcement (Week 5)** +- Enable organization-level 2FA requirement +- Monitor compliance in real-time +- Address escalations promptly + +**Compliance Monitoring:** +```bash +# Audit 2FA compliance +# Organization → People → Filter: "2FA disabled" + +# API approach +curl -H "Authorization: token {PAT}" \ + https://api.github.com/orgs/{ORG}/members?filter=2fa_disabled + +# Remove non-compliant users (after grace period) +gh api -X DELETE /orgs/{ORG}/members/{USERNAME} +``` + +### 2FA Recovery Procedures + +**User Lost 2FA Device:** + +**Option 1: Use Recovery Codes** +```bash +# User navigates to GitHub login +# Enters username and password +# Clicks "Enter a two-factor recovery code" +# Enters one of their 16-digit recovery codes +# Regenerates new recovery codes after login +``` + +**Option 2: Use Fallback 2FA Method** +```bash +# If SMS configured as fallback: +# User selects "Text me a verification code" +# Enters SMS code to authenticate +``` + +**Option 3: Organization Owner Recovery (Personal Accounts)** +```bash +# Organization owner can disable 2FA for user +# Organization → People → {User} → Manage → Disable 2FA +# User must re-enable 2FA to regain org access +``` + +**Option 4: GitHub Support (EMU)** +```bash +# For EMU accounts, contact GitHub Support +# Provide proof of identity and authorization +# Support can reset 2FA at enterprise level +``` + +**Best Practices:** +- Register multiple 2FA methods (TOTP + Security Key) +- Store recovery codes in password manager +- Document 2FA recovery process in runbooks +- Test recovery procedures quarterly + +--- + +## Advanced IAM Considerations + +### IP Allow Lists + +Restrict access to GitHub enterprise from approved IP ranges: + +**Configuration:** +```bash +# Enterprise → Settings → IP allow list +# Add allowed IP ranges: +# - Corporate VPN: 203.0.113.0/24 +# - Office networks: 198.51.100.0/24 +# - CI/CD runners: 192.0.2.50/32 + +# Enable enforcement: +# [ ] Enable IP allow list (blocks all other IPs) +# [ ] Allow GitHub Apps installed on the organization +``` + +**Exceptions:** +- GitHub Actions runners (managed by GitHub) +- Installed GitHub Apps (requires explicit permission) +- API access via PATs (if allowed in policy) + +### Audit Log Streaming + +Stream audit events to SIEM/logging platforms: + +**Supported Destinations:** +- Amazon S3 +- Azure Blob Storage +- Azure Event Hubs +- Google Cloud Storage +- Splunk +- Datadog + +**Configuration:** +```bash +# Enterprise → Settings → Audit log → Stream logs +# Select destination → Configure credentials +# Filter events: User login, PAT creation, repo access + +# Example: Stream to Azure Event Hubs +# Event Hub namespace: acme-github-logs +# Event Hub: github-audit-stream +# Shared access key: {CONNECTION_STRING} +``` + +**Critical Events to Monitor:** +- `oauth_access.create`: PAT generation +- `organization.add_member`: User provisioning +- `organization.remove_member`: User deprovisioning +- `repo.access`: Repository access attempts +- `protected_branch.policy_override`: Branch protection bypass + +### Just-in-Time (JIT) Access + +Implement temporary privilege escalation: + +**Approach 1: IdP Group-Based (Recommended)** +```bash +# 1. User requests elevated access via service portal +# 2. Approval workflow assigns user to privileged IdP group +# 3. SCIM syncs group membership to GitHub team +# 4. User gains org/repo permissions for time-boxed period +# 5. Automatic removal after expiration +``` + +**Approach 2: GitHub App with Fine-Grained Permissions** +```bash +# Develop custom GitHub App for JIT access +# 1. User requests access via Slack/Portal +# 2. App grants temporary collaborator access to repo +# 3. Lambda/Azure Function revokes access after TTL +``` + +### Identity Lifecycle Integration + +**Integration with HR Systems:** + +Common integrations for automated IAM: +- **Workday:** Identity provisioning and termination +- **BambooHR:** Onboarding/offboarding workflows +- **Namely:** Employee lifecycle events +- **SAP SuccessFactors:** Enterprise HR events + +**Architecture:** +```bash +# HR System → IdP → GitHub +# Example: Workday → Okta → GitHub EMU + +# 1. Workday: New employee record created +# 2. Workday Integration: Provisions user in Okta +# 3. Okta Workflow: Assigns user to GitHub EMU app +# 4. Okta SCIM: Provisions managed user on GitHub +# 5. Okta Groups: Assigns user to teams based on dept/role +``` + +### Cross-Organization Access Patterns + +**EMU with Multiple Organizations:** + +- Single enterprise with multiple organizations (business units, regions) +- Users provisioned at enterprise level, assigned to orgs via IdP groups +- Centralized IAM policy enforcement +- Consistent authentication across all organizations + +**Example:** +```bash +# Enterprise: acme-corp +# Organizations: +# - acme-platform (Platform Engineering) +# - acme-data (Data Engineering) +# - acme-mobile (Mobile Engineering) +# +# IdP Group Mapping: +# - "github-platform-team" → acme-platform org +# - "github-data-team" → acme-data org +# - "github-mobile-team" → acme-mobile org +# - "github-enterprise-admins" → All orgs (owner role) +``` + +--- + +## References + +### Official GitHub Documentation + +- [About Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users) +- [Choose an Enterprise Type](https://docs.github.com/en/enterprise-cloud@latest/enterprise-onboarding/getting-started-with-your-enterprise/choose-an-enterprise-type) +- [Configuring SAML SSO for Your Enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise) +- [Configuring SCIM Provisioning for EMU](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users) +- [Managing Team Memberships with IdP Groups](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups) +- [Enforcing Policies for Security Settings](https://docs.github.com/en/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise) +- [About SSH Certificate Authorities](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities) + +### Related Documentation + +- [Enterprise Managed Users Deep Dive](./04-enterprise-managed-users.md) - Comprehensive guide to EMU implementation and management +- [Teams and Permissions Management](./05-teams-permissions.md) - Role-based access control and team hierarchies +- [Security and Compliance](./06-security-compliance.md) - Enterprise security controls and compliance frameworks + +### External Resources + +#### Microsoft Entra ID (Azure AD) +- [Tutorial: Azure AD SSO Integration with GitHub](https://learn.microsoft.com/en-us/azure/active-directory/saas-apps/github-tutorial) +- [Configure SCIM Provisioning with GitHub EMU](https://learn.microsoft.com/en-us/azure/active-directory/saas-apps/github-enterprise-managed-user-provisioning-tutorial) +- [Conditional Access Policies Overview](https://learn.microsoft.com/en-us/azure/active-directory/conditional-access/overview) + +#### Okta +- [Okta GitHub EMU Integration Guide](https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-GitHub-Enterprise-Managed-User.html) +- [Okta Lifecycle Management](https://help.okta.com/en-us/Content/Topics/Provisioning/lcm/lcm-main.htm) +- [Okta Group Push to GitHub](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-group-push-main.htm) + +#### PingFederate +- [PingFederate SAML Configuration](https://docs.pingidentity.com/r/en-us/pingfederate-112/help_samlquickconnectiontasklet_samlquickconnectionstate) +- [PingFederate SP Connection Setup](https://docs.pingidentity.com/r/en-us/pingfederate-112/pf_sp_connections_overview) + +#### SAML & SCIM Standards +- [SAML 2.0 Specification (OASIS)](http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf) +- [SCIM 2.0 RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644) +- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) + +#### Security Best Practices +- [NIST Digital Identity Guidelines (SP 800-63)](https://pages.nist.gov/800-63-3/) +- [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html) +- [CIS GitHub Enterprise Benchmark](https://www.cisecurity.org/benchmark/github) + +--- + +**Document Version:** 1.0 +**Last Updated:** 2024 +**Target Audience:** Enterprise Administrators, Security Engineers, Identity & Access Management Teams +**Expertise Level:** L400 (Expert) + +For questions or feedback on this documentation, please contact your GitHub Customer Success Manager or Technical Account Manager. diff --git a/docs/04-enterprise-managed-users.md b/docs/04-enterprise-managed-users.md new file mode 100644 index 0000000..aed16e6 --- /dev/null +++ b/docs/04-enterprise-managed-users.md @@ -0,0 +1,1617 @@ +# Enterprise Managed Users (EMU) + +## Overview + +Enterprise Managed Users (EMU) represents GitHub's most secure and enterprise-grade identity management solution, providing organizations with complete control over the entire user lifecycle through direct integration with corporate Identity Providers (IdP). EMU fundamentally transforms how enterprises manage GitHub access by treating user accounts as managed resources provisioned and controlled by the organization rather than independently owned personal accounts. + +## What are Enterprise Managed Users? + +Enterprise Managed Users are GitHub user accounts that are fully owned, provisioned, and managed by an enterprise through an external Identity Provider. Unlike traditional personal GitHub accounts where users maintain independent control, EMU accounts are: + +- **Provisioned automatically** via SCIM (System for Cross-domain Identity Management) +- **Synchronized continuously** with your corporate identity provider +- **Controlled centrally** by enterprise administrators +- **Identified distinctly** with an `_shortcode` suffix (e.g., `octocat_acme`) +- **Lifecycle-managed** from provisioning through deprovisioning + +### EMU Architecture + +```mermaid +graph TB + subgraph "Identity Provider" + A[IdP User Directory] + B[IdP Groups] + C[SCIM Provisioning Engine] + end + + subgraph "GitHub Enterprise Cloud" + D[EMU Enterprise] + E[EMU Accounts] + F[Enterprise Organizations] + G[Teams] + H[Repositories] + end + + subgraph "Authentication Flow" + I[SAML/OIDC SSO] + end + + A -->|User Data| C + B -->|Group Memberships| C + C -->|SCIM API| D + D -->|Provision| E + E -->|Access Via| I + I -->|Authenticate| A + E -->|Member Of| F + F -->|Contains| G + G -->|Access| H + B -.->|Sync| G + + style D fill:#2ea44f + style E fill:#0969da + style C fill:#bf3989 +``` + +### How EMU Differs from Personal Accounts + +| Aspect | Personal Accounts | Enterprise Managed Users | +|--------|------------------|--------------------------| +| **Account Ownership** | User-owned | Enterprise-owned | +| **Provisioning** | Self-registration | IdP-provisioned via SCIM | +| **Authentication** | Username/password + 2FA | Enterprise SSO (SAML/OIDC) | +| **Username Format** | user choice | `username_shortcode` | +| **Email Domain** | Any email | Enterprise domain only | +| **Password Management** | User-controlled | IdP-controlled | +| **Account Recovery** | Self-service | Enterprise IT | +| **External Collaboration** | Full access | Enterprise-only (by default) | +| **Public Contributions** | Unrestricted | Restricted to enterprise repos | +| **Profile Customization** | Full control | Limited/managed | + +## EMU Value Proposition + +### 1. Centralized Identity Control + +EMU provides a **single source of truth** for user identity, eliminating the disconnect between corporate identity systems and GitHub access: + +- **Automatic provisioning**: New employees receive GitHub access as part of standard onboarding +- **Real-time synchronization**: Changes in IdP instantly reflect in GitHub +- **Group-based access**: IdP groups automatically map to GitHub teams +- **Consistent identity**: Same credentials across all enterprise systems + +### 2. Enhanced Security Posture + +EMU dramatically reduces security risks through enterprise-grade controls: + +**Identity Hardening:** +- Enforced SSO authentication (SAML 2.0 or OIDC) +- No local passwords or 2FA to manage +- Impossible for users to create backdoor access +- IdP MFA policies automatically enforced + +**Access Control:** +- Conditional access policies from IdP +- IP allowlist enforcement at enterprise level +- Session duration controls +- Device compliance requirements + +**Attack Surface Reduction:** +- No personal access tokens by default +- SSH keys managed centrally +- OAuth app restrictions +- GitHub App policies enforced + +### 3. Simplified Offboarding + +One of EMU's most powerful features is **instant access revocation**: + +```mermaid +sequenceDiagram + participant HR as HR System + participant IdP as Identity Provider + participant SCIM as SCIM Provisioner + participant GH as GitHub Enterprise + + Note over HR,GH: Employee Termination Event + + HR->>IdP: Disable user account + IdP->>SCIM: Trigger deprovisioning + SCIM->>GH: SCIM DELETE request + GH->>GH: Suspend EMU account + GH->>GH: Revoke all sessions + GH->>GH: Revoke all tokens + GH->>GH: Remove from all teams + GH-->>IdP: Confirmation + + Note over GH: User immediately loses all access + Note over GH: Repositories remain intact +``` + +**Offboarding Benefits:** +- Instant access termination (seconds, not hours/days) +- Automatic removal from all repositories and teams +- All sessions and tokens immediately revoked +- No orphaned accounts or lingering access +- Complete audit trail of access removal +- Repositories and contributions preserved + +### 4. Compliance Benefits + +EMU supports rigorous compliance requirements: + +**Audit and Reporting:** +- Complete user lifecycle audit trail +- Identity verification for compliance (SOC2, ISO 27001) +- Centralized access reviews +- Automated compliance reporting + +**Data Governance:** +- Enterprise owns all code and data +- No personal account mixing +- Clear data residency +- Simplified GDPR/privacy compliance + +**Regulatory Requirements:** +- Federal/government compliance (FedRAMP) +- Financial services regulations (SOX, FINRA) +- Healthcare standards (HIPAA) +- Industry-specific mandates + +### 5. Namespace Isolation + +EMU provides **complete namespace separation**: + +- Managed users cannot interact with personal GitHub accounts by default +- Enterprise code remains within enterprise boundaries +- Reduced risk of accidental public exposure +- Clear separation between work and personal contributions +- Protection against shadow IT + +### 6. Policy Enforcement + +Enterprise policies apply uniformly across all managed users: + +- **Repository policies**: Visibility, creation, deletion, forking +- **Security policies**: Secret scanning, dependency reviews, code scanning +- **Compliance policies**: Required workflows, branch protection +- **Collaboration policies**: Outside collaborator restrictions +- **Content policies**: Prohibited content scanning + +### 7. IP Allow Lists + +EMU enables network-level access control: + +```yaml +# Enterprise IP Allow List Configuration +Allowed IP Ranges: + - Corporate VPN: 203.0.113.0/24 + - Office Networks: 198.51.100.0/24 + - Cloud Infrastructure: 192.0.2.0/24 + - Trusted Partners: 198.51.100.128/25 + +Enforcement: + - Web UI Access: Enforced + - Git Operations: Enforced + - API Calls: Enforced + - GitHub Actions: Configurable +``` + +**IP Allowlist Capabilities:** +- Restrict access to known networks +- Prevent access from unauthorized locations +- Support for GitHub Actions with IP ranges +- Configuration at enterprise level +- Automatic application to all managed users + +### 8. Reduced Attack Surface + +EMU minimizes security exposure through architectural constraints: + +- Cannot create personal access tokens (unless specifically allowed) +- Cannot configure OAuth apps without approval +- Cannot participate in public GitHub community by default +- Cannot fork enterprise repositories to personal accounts +- Cannot invite external collaborators without enterprise settings +- Cannot change profile information arbitrarily + +## EMU vs Personal Accounts: Detailed Comparison + +```mermaid +graph LR + subgraph "Feature Comparison" + A[Authentication] + B[Repository Access] + C[External Collaboration] + D[Identity Management] + E[Compliance] + end + + subgraph "Personal Accounts" + PA1[Self-managed credentials] + PA2[Public & private repos] + PA3[Unrestricted] + PA4[User-controlled] + PA5[User responsibility] + end + + subgraph "EMU Accounts" + EM1[Enterprise SSO only] + EM2[Enterprise repos only] + EM3[Enterprise-controlled] + EM4[IdP-managed] + EM5[Enterprise enforced] + end + + A --> PA1 + A --> EM1 + B --> PA2 + B --> EM2 + C --> PA3 + C --> EM3 + D --> PA4 + D --> EM4 + E --> PA5 + E --> EM5 + + style EM1 fill:#2ea44f + style EM2 fill:#2ea44f + style EM3 fill:#2ea44f + style EM4 fill:#2ea44f + style EM5 fill:#2ea44f +``` + +### Feature-by-Feature Comparison Matrix + +| Feature Category | Personal Accounts | EMU Accounts | Best For | +|------------------|-------------------|--------------|----------| +| **Authentication & Identity** | +| Login Method | Username/password, SSO, or keys | Enterprise SSO only | EMU for security | +| Password Management | User-managed | IdP-managed | EMU for centralization | +| MFA Enforcement | User choice (unless org requires) | IdP policy enforced | EMU for compliance | +| Account Recovery | Self-service or support | Enterprise IT only | EMU for control | +| Username Format | Flexible | `username_shortcode` | Personal for flexibility | +| Email Addresses | Any email domain | Enterprise domain | EMU for validation | +| **Repository Access** | +| Public Repos | Full read/write access | Read-only (no contributions) | Personal for OSS | +| Private Personal Repos | Unlimited | Not available | Personal for personal work | +| Enterprise Repos | Via invitation | Default access | EMU for enterprise | +| Forking | To personal or org | Within enterprise only | Personal for flexibility | +| External Contributions | Unrestricted | Blocked by default | Personal for OSS work | +| **Collaboration** | +| Outside Collaborators | Can invite freely | Enterprise policy controlled | EMU for governance | +| External Teams | Can participate | Enterprise only | Personal for OSS | +| Gists | Public/secret | Private to enterprise | Personal for sharing | +| GitHub Pages | Public hosting | Enterprise-approved only | Personal for portfolio | +| GitHub Marketplace | Full access | Restricted access | Personal for tools | +| **Security & Compliance** | +| Access Tokens | User-generated | Centrally managed | EMU for security | +| SSH Keys | User-managed | Policy-controlled | EMU for control | +| GPG Keys | User-managed | Policy-controlled | EMU for compliance | +| OAuth Apps | User-approved | Enterprise-approved | EMU for governance | +| GitHub Apps | User-installed | Enterprise-controlled | EMU for security | +| Audit Logging | Limited | Comprehensive enterprise logs | EMU for compliance | +| IP Restrictions | Org-level only | Enterprise-enforced | EMU for security | +| **Administration** | +| Account Lifecycle | User-managed | Automated via IdP | EMU for efficiency | +| Offboarding | Manual removal | Automatic suspension | EMU for security | +| Profile Updates | User-controlled | IdP-synchronized | EMU for accuracy | +| Team Membership | Manual management | IdP group sync | EMU for automation | +| Access Reviews | Manual process | IdP-integrated | EMU for compliance | +| **Use Case Fit** | +| Open Source Development | ✅ Excellent | ❌ Not supported | Personal | +| Enterprise Development | ⚠️ Manual management | ✅ Optimal | EMU | +| Contractors/Vendors | ✅ Guest access works | ⚠️ Requires planning | Personal or hybrid | +| Personal Projects | ✅ Native support | ❌ Not available | Personal | +| Highly Regulated Industries | ⚠️ Requires configuration | ✅ Purpose-built | EMU | +| Mixed Work/Personal | ✅ One account | ❌ Requires separate accounts | Personal | + +### Decision Framework: When to Use EMU + +```mermaid +graph TD + Start[Choose Enterprise Type] + + Start --> Q1{Need complete
identity control?} + Q1 -->|Yes| Q2{All code is
enterprise IP?} + Q1 -->|No| Personal[Use Personal Accounts] + + Q2 -->|Yes| Q3{Have supported
IdP?} + Q2 -->|No| Hybrid[Consider Hybrid Model] + + Q3 -->|Yes| Q4{Can restrict
external contributions?} + Q3 -->|No| IDP[Implement Supported IdP First] + + Q4 -->|Yes| Q5{High compliance
requirements?} + Q4 -->|No| Evaluate[Evaluate Trade-offs] + + Q5 -->|Yes| EMU[Use EMU] + Q5 -->|No| CostBenefit[Cost-Benefit Analysis] + + CostBenefit -->|Benefits outweigh| EMU + CostBenefit -->|Limited benefit| Personal + + Evaluate --> EMU + Evaluate --> Personal + + style EMU fill:#2ea44f + style Personal fill:#0969da + style Hybrid fill:#bf3989 +``` + +## EMU Limitations and Considerations + +While EMU provides significant advantages, it's crucial to understand its constraints: + +### Technical Limitations + +**1. Public Repository Restrictions** +- ❌ Cannot create public repositories outside enterprise +- ❌ Cannot contribute to public repositories (issues, PRs, comments) +- ❌ Cannot fork public repositories to personal account +- ❌ Cannot participate in GitHub Discussions publicly +- ⚠️ Read-only access to public repositories maintained + +**2. External Collaboration Constraints** +- ❌ Cannot have personal repositories under managed account +- ❌ Cannot be added to non-enterprise organizations +- ❌ Cannot collaborate outside enterprise boundary (by default) +- ⚠️ Requires separate personal account for OSS contributions +- ⚠️ Complex process for external collaborators + +**3. Account and Profile Limitations** +- ❌ Cannot change username (managed by IdP) +- ❌ Limited profile customization +- ❌ Cannot merge with existing personal account +- ❌ No GitHub achievements or contribution graph outside enterprise +- ⚠️ Username always includes `_shortcode` suffix + +**4. Feature Access Restrictions** +- ❌ Cannot use GitHub Sponsors +- ❌ Cannot create or participate in public GitHub Pages +- ❌ Cannot use personal access tokens (unless policy allows) +- ❌ Limited GitHub Marketplace access +- ⚠️ GitHub Copilot requires enterprise license + +### Operational Considerations + +**1. Identity Provider Dependency** +- ⚠️ Critical dependency on IdP availability +- ⚠️ IdP outages block all GitHub access +- ⚠️ IdP misconfigurations can cause mass access issues +- ⚠️ SCIM sync delays affect user experience + +**2. Migration Complexity** +```yaml +Migration Challenges: + - Repository History: Must be migrated carefully + - Git History: Author attribution changes + - External References: May break links + - OAuth/Apps: Require reconfiguration + - Integrations: Need reconnection + - Training: Users need adaptation time + - Dual Accounts: Personal + EMU workflow complexity +``` + +**3. Contractor and Vendor Access** + +Managing external contributors requires careful planning: + +**Option A: Guest Collaborators** +- Create EMU accounts in IdP for vendors +- Requires IdP user management +- Full audit trail +- Can be time-consuming + +**Option B: OAuth App Access** +- Configure GitHub App for specific access +- More limited permissions +- Easier to provision +- Less integrated + +**Option C: Hybrid Approach** +- Maintain separate personal account enterprise +- Invite as outside collaborators +- More complex management +- Better for temporary access + +**4. Developer Experience Impact** +- Requires two GitHub accounts (personal + EMU) for developers who contribute to OSS +- Context switching between accounts +- Separate Git configurations +- SSH key management complexity +- Browser profile separation needed + +### Organizational Considerations + +**1. Change Management** +- Significant workflow changes for users +- Training requirements +- Potential resistance from developers +- Communication planning essential + +**2. Cost Implications** +- EMU requires GitHub Enterprise Cloud +- Per-seat licensing model +- IdP integration costs +- Potential consulting/implementation costs + +**3. Compliance vs. Flexibility Trade-off** +- Maximum security and control +- Reduced developer flexibility +- Potential productivity impact +- Cultural fit assessment needed + +## Supported Identity Providers + +EMU integrates with enterprise-grade identity providers using standard protocols: + +### Officially Supported IdPs + +| Identity Provider | SAML 2.0 | OIDC | SCIM 2.0 | Notes | +|-------------------|----------|------|----------|-------| +| **Microsoft Entra ID** (Azure AD) | ✅ | ✅ | ✅ | Recommended, best integration | +| **Okta** | ✅ | ✅ | ✅ | Full feature support | +| **PingFederate** | ✅ | ❌ | ✅ | SAML-only | +| **Generic OIDC** | ❌ | ✅ | ✅ | With supported SCIM provider | + +### Protocol Comparison: OIDC vs SAML + +```mermaid +graph TB + subgraph "OIDC Flow" + O1[User Access Request] + O2[Redirect to IdP] + O3[IdP Authentication] + O4[ID Token + Access Token] + O5[GitHub Validates Token] + O6[Access Granted] + end + + subgraph "SAML Flow" + S1[User Access Request] + S2[Redirect to IdP] + S3[IdP Authentication] + S4[SAML Assertion] + S5[GitHub Validates Assertion] + S6[Access Granted] + end + + O1 --> O2 --> O3 --> O4 --> O5 --> O6 + S1 --> S2 --> S3 --> S4 --> S5 --> S6 + + style O4 fill:#0969da + style S4 fill:#bf3989 +``` + +**OIDC Advantages:** +- Modern protocol built on OAuth 2.0 +- JSON Web Tokens (JWT) - easier to debug +- Better mobile/API support +- Standardized discovery endpoints +- Refresh token support + +**SAML Advantages:** +- Mature, widely deployed +- Extensive enterprise support +- Rich attribute mapping +- Strong enterprise adoption + +### SCIM Provisioning Requirements + +All EMU implementations require SCIM 2.0 for user lifecycle management: + +```yaml +SCIM Operations: + Required: + - Create User (POST /Users) + - Update User (PATCH /Users/{id}) + - Delete User (DELETE /Users/{id}) + - Get User (GET /Users/{id}) + - List Users (GET /Users) + - Create Group (POST /Groups) + - Update Group (PATCH /Groups/{id}) + - Get Group (GET /Groups/{id}) + - List Groups (GET /Groups) + + Attributes Synchronized: + - userName (required) + - name.givenName + - name.familyName + - emails (required) + - active (required) + - groups (required) + - roles +``` + +### IdP Setup Requirements + +**Prerequisites for all IdPs:** +1. Enterprise license for GitHub +2. IdP admin access +3. SCIM provisioning capability +4. SSO (SAML or OIDC) capability +5. User group management +6. Custom attribute support + +**Microsoft Entra ID Specific:** +- Azure AD Premium P1/P2 or Microsoft 365 Business +- Enterprise Application registration +- App roles configuration +- Group-based assignment +- Conditional access policies (optional) + +**Okta Specific:** +- Okta Workforce Identity +- SCIM provisioning enabled +- App integration from catalog +- Group push configuration +- Custom attribute mapping + +## EMU Configuration Best Practices + +### IdP Group Mapping Strategy + +```mermaid +graph LR + subgraph "Identity Provider" + IG1[Engineering Department] + IG2[Backend Team] + IG3[Frontend Team] + IG4[DevOps Team] + IG5[Security Group] + end + + subgraph "GitHub Enterprise" + subgraph "Organization: Acme Corp" + GT1[backend-developers] + GT2[frontend-developers] + GT3[devops-engineers] + GT4[security-team] + end + end + + IG1 -.->|Contains| IG2 + IG1 -.->|Contains| IG3 + IG1 -.->|Contains| IG4 + + IG2 -->|Maps to| GT1 + IG3 -->|Maps to| GT2 + IG4 -->|Maps to| GT3 + IG5 -->|Maps to| GT4 + + GT1 -->|Access| R1[Backend Repos] + GT2 -->|Access| R2[Frontend Repos] + GT3 -->|Access| R3[Infrastructure Repos] + GT4 -->|Access| R4[Security Repos] + + style IG1 fill:#bf3989 + style GT1 fill:#2ea44f + style GT2 fill:#2ea44f + style GT3 fill:#2ea44f + style GT4 fill:#2ea44f +``` + +**Best Practices for Group Mapping:** + +1. **Use Hierarchical Structure** + ```yaml + IdP Group Hierarchy: + - company-all (root) + - engineering + - engineering-backend + - engineering-frontend + - engineering-devops + - product + - security + + GitHub Team Structure: + - Organization: acme-corp + - Team: engineering (parent) + - backend-team (child) + - frontend-team (child) + - devops-team (child) + - Team: product-team + - Team: security-team + ``` + +2. **Naming Conventions** + - **IdP Groups**: Use descriptive, hierarchical names (`eng-backend-services`) + - **GitHub Teams**: Mirror IdP structure (`backend-services`) + - **Consistency**: Maintain parallel naming across systems + - **Prefixes**: Consider role prefixes (`role-admin-`, `team-`, `project-`) + +3. **Role-Based Access Control (RBAC)** + ```yaml + Access Pattern Examples: + + Repository Access: + - Group: "github-repo-myapp-read" + Team: "myapp-readers" + Permission: Read + + - Group: "github-repo-myapp-write" + Team: "myapp-developers" + Permission: Write + + - Group: "github-repo-myapp-admin" + Team: "myapp-maintainers" + Permission: Admin + + Organization Roles: + - Group: "github-org-owner" + Role: Organization Owner + + - Group: "github-org-billing" + Role: Billing Manager + + - Group: "github-enterprise-admin" + Role: Enterprise Owner + ``` + +4. **Dynamic vs Static Groups** + - **Dynamic Groups**: Based on user attributes (department, location, role) + - **Static Groups**: Manually managed membership + - **Recommendation**: Prefer dynamic for scalability + +5. **Group Sync Configuration** + ```yaml + Sync Settings: + Frequency: Real-time (event-driven) or scheduled + Conflict Resolution: IdP is source of truth + Orphaned Teams: Preserve or remove based on policy + Audit Logging: Enable comprehensive logging + Error Notifications: Alert on sync failures + ``` + +### Team Synchronization Architecture + +**Sync Flow:** +1. User added to IdP group +2. IdP triggers SCIM notification +3. GitHub receives group membership update +4. User automatically added to GitHub team +5. User inherits team repository permissions +6. Audit log records change + +**Sync Failure Handling:** +```yaml +Common Sync Issues: + - API Rate Limits: Implement backoff strategy + - Network Failures: Retry with exponential backoff + - Invalid Mappings: Alert and require manual fix + - Permission Conflicts: Log and escalate + - Orphaned Users: Define retention policy +``` + +### RBAC Implementation Patterns + +**Pattern 1: Repository-Centric** +```yaml +Structure: + For each repository: + - {repo}-read (team with read) + - {repo}-write (team with write) + - {repo}-admin (team with admin) + +Pros: + - Granular control per repository + - Clear permission boundaries + - Easy to audit + +Cons: + - Team proliferation + - Complex management at scale + - Higher IdP group count +``` + +**Pattern 2: Role-Centric** +```yaml +Structure: + Global roles: + - developers (write to most repos) + - senior-developers (admin to most repos) + - viewers (read to all repos) + - security (admin to security repos) + +Pros: + - Fewer teams to manage + - Simpler mental model + - Scalable + +Cons: + - Less granular + - Potential over-permissioning + - Requires careful planning +``` + +**Pattern 3: Hybrid** +```yaml +Structure: + - Base roles for common access + - Specific teams for sensitive repos + - Project-based teams for initiatives + - Service account teams for automation + +Recommended: + This approach balances flexibility and control +``` + +### Naming Conventions + +**Usernames:** +- Format: `{idp_username}_{enterprise_shortcode}` +- Example: `jsmith_acme`, `agarcia_acme` +- Cannot be changed after creation +- Must be unique across GitHub + +**Email Addresses:** +- Must match enterprise verified domains +- Primary email from IdP is used +- Secondary emails can be added via IdP +- Email changes sync from IdP + +**Team Names:** +- Use kebab-case: `backend-services`, `frontend-web` +- Mirror IdP group names where possible +- Include organization prefix for large enterprises +- Avoid abbreviations that aren't clear + +**Organization Names:** +- Use descriptive names: `acme-corp`, `acme-engineering` +- Consider department or business unit structure +- Plan for growth and organizational changes + +### Contractors and External Collaborators + +**Strategy 1: IdP Guest Accounts** +```yaml +Approach: + - Create guest accounts in IdP + - Assign to specific groups + - Provision as EMU accounts + - Limit access scope + +Pros: + - Full audit trail + - Centralized management + - Consistent access control + - Easy offboarding + +Cons: + - IdP guest license costs + - Administrative overhead + - Onboarding delays + +Best For: + - Long-term contractors + - Strategic partners + - Frequent collaborators +``` + +**Strategy 2: Outside Collaborators (Personal Accounts)** +```yaml +Approach: + - Invite via personal GitHub account + - Grant repository-specific access + - Cannot be added to teams + - Limited organization visibility + +Pros: + - No IdP management needed + - Quick onboarding + - No additional licenses + - Familiar for contractors + +Cons: + - Outside enterprise boundary + - Limited audit trail + - Manual management + - No IdP integration + +Best For: + - Short-term contractors + - Open source collaborators + - One-off contributors +``` + +**Strategy 3: Separate Organization** +```yaml +Approach: + - Create separate GitHub organization + - Use personal accounts + - Share specific repositories + - Maintain boundary + +Pros: + - Clear separation + - Flexible collaboration + - No EMU constraints + +Cons: + - Additional organization to manage + - Repository duplication or syncing + - Complex access patterns + +Best For: + - External partnerships + - Multi-company projects + - Mixed collaboration models +``` + +**Recommendation Matrix:** + +| Duration | Trust Level | Access Scope | Recommended Strategy | +|----------|-------------|--------------|----------------------| +| < 1 month | Low | Single repo | Outside Collaborator | +| 1-6 months | Medium | Multiple repos | Outside Collaborator or IdP Guest | +| 6+ months | High | Organization-wide | IdP Guest Account | +| Ongoing | High | Enterprise-wide | IdP Guest Account | +| Partner | Varies | Specific projects | Separate Organization | + +## EMU Migration Strategies + +### Migration from Personal Accounts to EMU + +Migrating from personal accounts to EMU is a **one-way, irreversible** transition that requires careful planning: + +```mermaid +graph TD + Start[Current State: Personal Accounts] + + Start --> Phase1[Phase 1: Assessment] + Phase1 --> P1A[Inventory repositories] + Phase1 --> P1B[Identify users] + Phase1 --> P1C[Document integrations] + Phase1 --> P1D[Review external access] + + P1A --> Phase2[Phase 2: Planning] + P1B --> Phase2 + P1C --> Phase2 + P1D --> Phase2 + + Phase2 --> P2A[Design IdP structure] + Phase2 --> P2B[Plan migration timeline] + Phase2 --> P2C[Prepare communication] + Phase2 --> P2D[Setup test environment] + + P2A --> Phase3[Phase 3: IdP Configuration] + P2B --> Phase3 + P2C --> Phase3 + P2D --> Phase3 + + Phase3 --> P3A[Configure SCIM] + Phase3 --> P3B[Setup SSO] + Phase3 --> P3C[Map groups] + Phase3 --> P3D[Test provisioning] + + P3A --> Phase4[Phase 4: Repository Migration] + P3B --> Phase4 + P3C --> Phase4 + P3D --> Phase4 + + Phase4 --> P4A[Transfer repositories] + Phase4 --> P4B[Update permissions] + Phase4 --> P4C[Migrate integrations] + Phase4 --> P4D[Update documentation] + + P4A --> Phase5[Phase 5: User Transition] + P4B --> Phase5 + P4C --> Phase5 + P4D --> Phase5 + + Phase5 --> P5A[Provision EMU accounts] + Phase5 --> P5B[User training] + Phase5 --> P5C[Cutover] + Phase5 --> P5D[Monitor and support] + + P5A --> End[New State: EMU] + P5B --> End + P5C --> End + P5D --> End + + style Start fill:#bf3989 + style End fill:#2ea44f + style Phase1 fill:#0969da + style Phase2 fill:#0969da + style Phase3 fill:#0969da + style Phase4 fill:#0969da + style Phase5 fill:#0969da +``` + +### Phase 1: Assessment (2-4 weeks) + +**Repository Inventory:** +```bash +# Gather critical information +- Total repository count +- Repository ownership and access patterns +- Repository visibility (public/private/internal) +- Repository size and activity +- Branch protection rules +- CODEOWNERS files +- GitHub Actions workflows +- Secrets and variables +- Deploy keys +- Webhooks +``` + +**User Analysis:** +```yaml +User Categories: + - Full-time employees: Migrate to EMU + - Contractors: Decide on strategy + - External collaborators: Outside collaborator approach + - Service accounts: Bot/service account strategy + - Departed users: Archive or remove + +Questions to Answer: + - How many active users? + - What are their roles? + - Who needs OSS access? + - What IdP groups exist? + - Current authentication methods? +``` + +**Integration Audit:** +```yaml +Integrations to Review: + - GitHub Apps (installed) + - OAuth Apps (authorized) + - Personal Access Tokens (in use) + - Deploy keys (configured) + - Webhooks (active) + - CI/CD systems + - Project management tools + - Security scanning tools + - Monitoring systems +``` + +### Phase 2: Planning (2-4 weeks) + +**IdP Structure Design:** +```yaml +Group Design: + - Organization membership groups + - Team membership groups + - Role-based access groups + - Repository access groups + - Admin/special access groups + +Naming Standards: + - Prefix conventions + - Hierarchy structure + - Attribute mapping + - Shortcode selection +``` + +**Migration Timeline:** +```yaml +Recommended Approach: + Week 1-2: Assessment complete + Week 3-4: Planning and design + Week 5-6: IdP configuration + Week 7-8: Test environment setup + Week 9-10: Pilot with small team + Week 11-12: Phased rollout begins + Week 13-16: Full migration + Week 17+: Hypercare and optimization + +Critical Path Items: + - IdP configuration (blocking) + - SCIM setup (blocking) + - EMU enterprise creation (blocking) + - User communication (parallel) + - Repository transfer (phased) +``` + +**Communication Plan:** +```yaml +Stakeholders: + - Executive leadership: Business case, timeline + - Engineering leadership: Technical impact, benefits + - Developers: Workflow changes, training + - IT/Security: IdP integration, support + - External partners: Access changes + +Key Messages: + - Why EMU? (security, compliance, efficiency) + - What changes? (authentication, workflows) + - When? (timeline and milestones) + - How to prepare? (action items) + - Support available? (resources, contacts) +``` + +### Phase 3: IdP Configuration (2-3 weeks) + +**SCIM Configuration:** +```yaml +Steps: + 1. Create enterprise application in IdP + 2. Configure SCIM endpoint + 3. Set SCIM bearer token + 4. Map attributes: + - userName → username + - name.givenName → first name + - name.familyName → last name + - emails[primary] → email + - active → account status + 5. Test provisioning with test users + 6. Verify deprovisioning works + 7. Configure group sync +``` + +**SSO Configuration:** +```yaml +SAML/OIDC Setup: + 1. Configure SSO in IdP + 2. Set GitHub as service provider + 3. Configure attribute mapping + 4. Set up claim/attribute assertions + 5. Test SSO flow + 6. Enable MFA enforcement + 7. Configure conditional access (if applicable) + 8. Document recovery procedures +``` + +**Group Mapping:** +```yaml +Implementation: + 1. Create GitHub teams structure + 2. Create corresponding IdP groups + 3. Configure group sync + 4. Test membership changes + 5. Verify permission inheritance + 6. Document mapping +``` + +### Phase 4: Repository Migration (4-6 weeks) + +**Transfer Process:** +```bash +# Option 1: Repository Transfer (Recommended) +# Preserves all history, issues, PRs, settings +1. Transfer repository to EMU organization +2. Update repository permissions +3. Update branch protection rules +4. Verify GitHub Actions workflows +5. Update documentation + +# Option 2: Fresh Import +# Use when restructuring or cleaning +1. Create new repository in EMU org +2. Push code from old repository +3. Migrate issues (via API or tools) +4. Recreate branch protections +5. Reconfigure settings +``` + +**Post-Transfer Checklist:** +```yaml +For Each Repository: + - Verify all branches transferred + - Check branch protection rules + - Validate GitHub Actions workflows + - Test deploy keys/secrets + - Update CODEOWNERS + - Verify webhooks + - Test CI/CD pipelines + - Update external references + - Communicate new URL to team +``` + +### Phase 5: User Transition (2-4 weeks) + +**EMU Account Provisioning:** +```yaml +Provisioning Process: + 1. Assign users to IdP groups + 2. SCIM provisions EMU accounts + 3. Users receive welcome email + 4. Users perform first SSO login + 5. Verify team memberships + 6. Grant additional permissions as needed + 7. Provide training materials +``` + +**User Training:** +```yaml +Training Topics: + - SSO login process + - Username format change + - Two-account strategy (EMU + personal) + - Git configuration updates + - SSH key management + - Personal vs. work separation + - Troubleshooting common issues + - Where to get help + +Delivery Methods: + - Live training sessions + - Recorded videos + - Written documentation + - Office hours + - Slack/Teams channel +``` + +**Cutover:** +```yaml +Phased Approach (Recommended): + Phase A: Pilot team (1 week) + - Select small, representative team + - Provision EMU accounts + - Monitor closely + - Gather feedback + - Adjust as needed + + Phase B: Early adopters (2 weeks) + - Expand to volunteers + - Multiple teams + - Continue monitoring + - Refine processes + + Phase C: General availability (4-6 weeks) + - Department by department + - Or project by project + - Continue support + + Phase D: Completion + - Final stragglers + - Archive old accounts + - Complete documentation +``` + +### Change Management Best Practices + +**Before Migration:** +- Secure executive sponsorship +- Build cross-functional team (IT, Security, Engineering) +- Document current state thoroughly +- Create rollback plan (though limited with EMU) +- Set up helpdesk/support processes + +**During Migration:** +- Communicate frequently and transparently +- Provide multiple support channels +- Monitor metrics (adoption, issues, satisfaction) +- Be flexible and responsive to feedback +- Celebrate milestones + +**After Migration:** +- Conduct retrospective +- Document lessons learned +- Optimize IdP group structure +- Review and update policies +- Plan continuous improvement + +### Common Migration Challenges + +| Challenge | Impact | Mitigation | +|-----------|--------|------------| +| Developer resistance | Slow adoption | Clear communication, executive support, show benefits | +| OSS contribution workflow | Productivity | Document dual-account workflow, provide tooling | +| Integration breakage | Service disruption | Thorough testing, phased rollout, quick support | +| IdP sync issues | Access problems | Robust monitoring, clear escalation, IdP expertise | +| External collaborator access | Project delays | Plan external access strategy early | +| Git configuration | User frustration | Provide scripts, clear documentation, office hours | +| Repository URL changes | Broken links | Update documentation, use redirects where possible | +| Loss of contribution history | Morale | Explain limitations, acknowledge contributions | + +## EMU Operational Excellence + +### Monitoring and Observability + +**Key Metrics to Track:** + +```yaml +Health Metrics: + - SSO success rate + - SSO latency + - SCIM sync success rate + - SCIM sync duration + - User provisioning time + - Deprovisioning time + - Group sync accuracy + +Usage Metrics: + - Active user count + - Login frequency + - Failed login attempts + - Team membership changes + - Repository access patterns + - API rate limit consumption + +Security Metrics: + - Unauthorized access attempts + - Policy violations + - IP allowlist hits/blocks + - Token usage patterns + - Privilege escalation events +``` + +**Monitoring Tools:** +```yaml +GitHub: + - Audit log streaming + - GitHub Advanced Security alerts + - GitHub Actions usage metrics + - API rate limit monitoring + +IdP: + - Provisioning logs + - Authentication logs + - Group membership changes + - Error rates + +SIEM Integration: + - Stream audit logs to SIEM + - Create correlation rules + - Set up alerting + - Build dashboards +``` + +**Alerting Strategy:** +```yaml +Critical Alerts (Immediate Response): + - SCIM provisioning failures (> 5 in 10 min) + - SSO complete outage + - Mass deprovisioning events (> 10 users) + - Enterprise owner changes + - Security policy modifications + +Warning Alerts (Review Within Hours): + - SCIM sync delays (> 5 minutes) + - SSO elevated error rates (> 5%) + - Unusual access patterns + - Failed privilege escalation attempts + - API rate limit approaching + +Info Alerts (Daily Review): + - User provisioning stats + - Team membership changes + - Repository creation/deletion + - External collaborator invitations +``` + +### Troubleshooting Guide + +**Issue: User Cannot Log In** +```yaml +Symptoms: + - SSO fails + - User gets access denied + - Redirect loop + +Troubleshooting Steps: + 1. Verify user exists in IdP + 2. Check IdP account is active + 3. Verify user assigned to GitHub app in IdP + 4. Check SCIM provisioning status + 5. Verify EMU account exists in GitHub + 6. Check EMU account is not suspended + 7. Review IdP authentication logs + 8. Review GitHub audit logs + 9. Test SSO configuration with test user + 10. Check IP allowlist if configured + +Common Causes: + - User not assigned to IdP app + - SCIM provisioning failed + - Account suspended + - IP allowlist blocking + - IdP configuration issue + - SSO certificate expired +``` + +**Issue: SCIM Sync Failures** +```yaml +Symptoms: + - Users not provisioned + - Group membership not syncing + - User updates not reflecting + +Troubleshooting Steps: + 1. Check SCIM endpoint accessibility + 2. Verify SCIM token validity + 3. Review IdP provisioning logs + 4. Check GitHub API rate limits + 5. Verify IdP group mappings + 6. Test SCIM provisioning manually + 7. Check network connectivity + 8. Review error messages in IdP + +Common Causes: + - Expired SCIM token + - Network connectivity issues + - Rate limit exceeded + - Invalid attribute mapping + - IdP service disruption + - Malformed SCIM requests +``` + +**Issue: Incorrect Team Memberships** +```yaml +Symptoms: + - User in wrong teams + - Missing team access + - Unexpected access + +Troubleshooting Steps: + 1. Verify user's IdP group memberships + 2. Check IdP-to-GitHub group mapping + 3. Review SCIM group sync logs + 4. Manually trigger group sync + 5. Check for nested group issues + 6. Review team sync configuration + 7. Verify team slug matches mapping + +Common Causes: + - Incorrect IdP group membership + - Mapping configuration error + - Sync delay + - Nested group not supported + - Team renamed in GitHub +``` + +**Issue: IdP Outage Impact** +```yaml +Impact: + - No new SSO logins possible + - Existing sessions continue to work + - No new user provisioning + - No group sync updates + +Mitigation: + - Existing Git credentials still work (SSH keys, tokens) + - Active browser sessions remain valid + - GitHub Actions continue to run + - Service accounts unaffected + +Recovery: + 1. Wait for IdP restoration + 2. Verify SSO working + 3. Trigger SCIM sync if needed + 4. Check for sync backlog + 5. Verify critical users have access + 6. Communicate status to users +``` + +### IdP Sync Failure Resolution + +```mermaid +graph TD + Start[Sync Failure Detected] + + Start --> Check1{IdP
Accessible?} + Check1 -->|No| Fix1[Resolve IdP connectivity] + Check1 -->|Yes| Check2{SCIM Token
Valid?} + + Fix1 --> Retest1[Test Sync] + + Check2 -->|No| Fix2[Rotate SCIM token] + Check2 -->|Yes| Check3{Rate Limit
Hit?} + + Fix2 --> Retest1 + + Check3 -->|Yes| Fix3[Wait for reset/optimize] + Check3 -->|No| Check4{Attribute
Mapping OK?} + + Fix3 --> Retest1 + + Check4 -->|No| Fix4[Fix attribute mapping] + Check4 -->|Yes| Check5{Network
Issues?} + + Fix4 --> Retest1 + + Check5 -->|Yes| Fix5[Resolve network] + Check5 -->|No| Escalate[Escalate to GitHub Support] + + Fix5 --> Retest1 + + Retest1 --> Success{Success?} + Success -->|Yes| End[Resolved] + Success -->|No| Escalate + + style Start fill:#bf3989 + style End fill:#2ea44f + style Escalate fill:#d73a4a +``` + +### Audit Log Analysis + +**Critical Events to Monitor:** + +```yaml +Authentication Events: + - org.sso_response (SSO logins) + - user.failed_login (failed attempts) + - user.suspend (account suspensions) + - user.unsuspend (account reactivations) + +Provisioning Events: + - user.create (SCIM user creation) + - user.remove (SCIM user deletion) + - team.add_member (team additions) + - team.remove_member (team removals) + +Administrative Events: + - org.update_member (permission changes) + - org.add_member (new members) + - org.remove_member (member removal) + - enterprise.config.update (config changes) + +Security Events: + - repo.access (repository access) + - repo.download_zip (bulk downloads) + - git.clone (repository clones) + - org.oauth_app.* (OAuth app events) + - personal_access_token.* (PAT events) +``` + +**Sample Audit Log Queries:** + +```bash +# Failed SSO attempts in last hour +action:org.sso_response result:failure created:>=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ) + +# Mass deprovisioning events +action:user.remove created:>=$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ) | count + +# Privilege escalation to owner +action:org.update_member permission:admin + +# External IP access attempts (if IP allowlist enabled) +action:org.sso_response blocked:true + +# Token creation outside IdP +action:personal_access_token.create +``` + +**Audit Log Streaming Setup:** +```yaml +Destinations: + - Splunk + - Azure Sentinel + - AWS Security Lake + - Google Chronicle + - Datadog + +Benefits: + - Real-time alerting + - Long-term retention + - Advanced analytics + - Compliance reporting + - Incident response +``` + +### Operational Runbooks + +**Runbook: Emergency User Access** +```yaml +Scenario: Executive needs immediate access during IdP outage + +NOT POSSIBLE with EMU: + - Cannot bypass SSO + - Cannot create local credentials + - Cannot manually provision + +Alternatives: + - Use existing session if active + - Use GitHub CLI with existing token + - Use SSH key for Git operations + - Wait for IdP restoration + +Prevention: + - High IdP availability SLA + - IdP failover/redundancy + - Service account strategy + - GitHub Actions for automation +``` + +**Runbook: Bulk User Offboarding** +```yaml +Scenario: Department closure, mass layoff + +Steps: + 1. Identify users in IdP + 2. Remove from IdP groups (or disable accounts) + 3. SCIM automatically: + - Suspends EMU accounts + - Revokes sessions + - Removes team memberships + 4. Verify deprovisioning in GitHub + 5. Review repository ownership + 6. Transfer repository ownership if needed + 7. Document for compliance + +Timeline: + - User removed from IdP: Immediate + - SCIM deprovisioning: < 5 minutes + - All access revoked: < 10 minutes +``` + +**Runbook: Repository Access Emergency** +```yaml +Scenario: Critical repository needs immediate access for incident response + +Steps: + 1. Identify user needing access + 2. Add user to appropriate IdP group + 3. Wait for SCIM sync (< 5 min) or trigger manual sync + 4. Verify user in GitHub team + 5. Confirm repository access + 6. Document access grant in incident log + 7. Remove access post-incident if temporary + +If IdP unavailable: + 1. Add as outside collaborator (if allowed by policy) + 2. Use service account + 3. Use existing team member +``` + +### Performance Optimization + +**SCIM Sync Optimization:** +```yaml +Best Practices: + - Use incremental sync instead of full sync + - Schedule sync during off-peak hours + - Batch operations where possible + - Monitor and tune sync frequency + - Use IdP change notifications (event-driven) + +Typical Sync Times: + - Single user: < 10 seconds + - 100 users: < 2 minutes + - 1000 users: < 20 minutes + - Full sync (10,000 users): < 2 hours +``` + +**SSO Performance:** +```yaml +Optimization Tips: + - Use OIDC for better performance + - Minimize SAML assertion size + - Optimize attribute mapping + - Use IdP session caching + - Monitor SSO latency + - Implement IdP load balancing + +Target Metrics: + - SSO redirect: < 500ms + - IdP authentication: < 2s + - Assertion validation: < 500ms + - Total SSO flow: < 5s +``` + +## References + +### Official Documentation +- [About Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users) +- [Choosing an Enterprise Type](https://docs.github.com/en/enterprise-cloud@latest/enterprise-onboarding/getting-started-with-your-enterprise/choose-an-enterprise-type) +- [Configuring SCIM for EMU](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users) +- [Abilities and Restrictions of Managed User Accounts](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts) +- [Configuring SAML SSO for EMU](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-saml-single-sign-on-for-enterprise-managed-users) +- [Configuring OIDC for EMU](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-oidc-for-iam/configuring-oidc-for-enterprise-managed-users) + +### Identity Provider Guides +- [Configuring Azure AD for EMU](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-azure-active-directory) +- [Configuring Okta for EMU](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta) +- [Configuring PingFederate for EMU](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-pingfederate) + +### Related Documentation +- [Identity and Access Management Guide](./03-identity-access-management.md) +- [Teams and Permissions](./02-teams-permissions.md) +- [Security and Compliance](./05-security-compliance.md) +- [GitHub Audit Logs](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) +- [SCIM Specification (RFC 7644)](https://datatracker.ietf.org/doc/html/rfc7644) +- [SAML 2.0 Specification](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html) +- [OpenID Connect Core Specification](https://openid.net/specs/openid-connect-core-1_0.html) + +### Additional Resources +- [GitHub Enterprise Blog: EMU Announcements](https://github.blog/tag/enterprise-managed-users/) +- [GitHub Skills: GitHub Administration](https://skills.github.com/) +- [GitHub Support: EMU Troubleshooting](https://support.github.com/) +- [GitHub Community Forum: EMU Discussions](https://github.community/) + +--- + +*This document is part of the GitHub Administration Best Practices and Compliance Series (GitHub ABCs). For the complete series, see the [main documentation index](./README.md).* diff --git a/docs/05-teams-permissions.md b/docs/05-teams-permissions.md new file mode 100644 index 0000000..79e1f3a --- /dev/null +++ b/docs/05-teams-permissions.md @@ -0,0 +1,1549 @@ +# Teams and Permissions + +## Overview + +GitHub's teams and permissions system provides a sophisticated framework for organizing members and controlling access across repositories and organizational resources. Understanding the intricacies of team hierarchies, permission inheritance, and role-based access control is essential for designing scalable access management strategies in enterprise environments. + +This guide explores advanced team structures, nested team relationships, permission cascading mechanisms, and the integration of teams with identity provider (IdP) synchronization for centralized access management. + +## Team Types and Visibility + +GitHub teams support two visibility modes that control who can see team membership and mentions: + +### Visible Teams + +**Characteristics:** +- Default team type for organizations +- All organization members can see the team and its members +- Any member can @mention the team +- Team discussions are visible to all organization members +- Ideal for cross-functional collaboration and transparency + +**Use Cases:** +- Engineering teams (frontend, backend, infrastructure) +- Cross-functional groups (security, DevOps, platform) +- Public-facing teams that coordinate with multiple departments + +### Secret Teams + +**Characteristics:** +- Only team members and organization owners can see the team +- Team mentions are restricted to team members +- Team discussions are private to members +- Must be explicitly granted access by organization owners +- Cannot be nested under visible teams + +**Use Cases:** +- Security incident response teams +- Compliance and audit teams +- Executive leadership teams +- Teams handling sensitive data or projects +- Temporary teams for confidential initiatives + +**Visibility Implications:** + +```yaml +Visible Team: + - Discoverable: Yes + - Mentionable: All org members + - Parent Teams: Can be visible or secret + - Child Teams: Can be visible or secret + +Secret Team: + - Discoverable: No (owners and members only) + - Mentionable: Members only + - Parent Teams: Must be secret + - Child Teams: Must be secret +``` + +## Nested Teams and Hierarchy + +Nested teams enable sophisticated organizational structures that mirror company hierarchies while providing powerful permission inheritance mechanisms. + +### Team Hierarchy Structure + +```mermaid +graph TD + A[Engineering Team
Secret] --> B[Platform Team
Visible] + A --> C[Product Teams
Visible] + A --> D[Security Team
Secret] + + B --> B1[Infrastructure
Visible] + B --> B2[DevOps
Visible] + B --> B3[SRE
Visible] + + C --> C1[Mobile Team
Visible] + C --> C2[Web Team
Visible] + C --> C3[API Team
Visible] + + D --> D1[AppSec
Secret] + D --> D2[Incident Response
Secret] + + style A fill:#ff6b6b + style D fill:#ff6b6b + style D1 fill:#ff6b6b + style D2 fill:#ff6b6b + style B fill:#4ecdc4 + style C fill:#4ecdc4 + style B1 fill:#95e1d3 + style B2 fill:#95e1d3 + style B3 fill:#95e1d3 + style C1 fill:#95e1d3 + style C2 fill:#95e1d3 + style C3 fill:#95e1d3 +``` + +### Parent/Child Team Inheritance + +**Access Inheritance Rules:** + +1. **Repository Access:** + - Child teams inherit all repository access from parent teams + - Child teams can have additional repositories not granted to parents + - Child teams cannot have less access than parents (only equal or greater) + - Permission level inheritance follows the maximum level granted + +2. **Permission Cascading:** + - If parent has `Write` access, child automatically has `Write` minimum + - Child can be granted `Admin` while parent has `Write` + - Removing parent's access doesn't remove child's explicit grants + - Child's effective permission = max(parent permission, direct permission) + +**Example Inheritance:** + +``` +Engineering Team (Parent) +├── Repository: core-api (Write) +├── Repository: infrastructure (Admin) +└── Backend Team (Child) + ├── Inherits: core-api (Write) + ├── Inherits: infrastructure (Admin) + ├── Direct: backend-services (Admin) + └── Effective Access: + - core-api: Write (inherited) + - infrastructure: Admin (inherited) + - backend-services: Admin (direct) +``` + +### Permission Cascading Mechanics + +**Cascading Behavior:** + +```mermaid +graph LR + A[Parent Team
Read Access] --> B[Child Team
Inherited: Read] + B --> C[Grandchild Team
Inherited: Read] + + D[Parent Team
Write Access] --> E[Child Team
Direct: Admin] + E --> F[Grandchild Team
Inherited: Admin] + + G[Parent Team
Admin Access] --> H[Child Team
No Direct Grant] + H --> I[Grandchild Team
Direct: Write] + + style A fill:#ffd93d + style B fill:#ffd93d + style C fill:#ffd93d + style D fill:#6bcf7f + style E fill:#4d96ff + style F fill:#4d96ff + style G fill:#4d96ff + style H fill:#4d96ff + style I fill:#6bcf7f +``` + +**Cascading Rules:** +- Permissions flow down, never up +- Explicit grants always take precedence over inheritance +- Removing a parent team does not remove child's explicit access +- Multiple inheritance paths result in highest permission level +- Organization base permissions act as absolute minimum + +### Nested Team Best Practices + +**Structural Guidelines:** + +1. **Maximum Depth:** Limit nesting to 3-4 levels for maintainability +2. **Visibility Consistency:** Secret teams should have secret parents +3. **Permission Clarity:** Document expected inheritance patterns +4. **Ownership Model:** Assign team maintainers at each level +5. **Naming Convention:** Use consistent prefixes (e.g., `eng-platform-sre`) + +**Anti-Patterns to Avoid:** + +```yaml +# DON'T: Deep nesting reduces clarity +org-engineering-platform-infrastructure-kubernetes-operators-team + +# DO: Flat structure with clear naming +engineering-k8s-operators + +# DON'T: Mix visibility in hierarchy +Parent: Secret Team +└── Child: Visible Team # Creates confusion + +# DO: Consistent visibility +Parent: Secret Team +└── Child: Secret Team +``` + +## Team Synchronization with Identity Provider + +Team sync enables automatic team membership management through IdP groups, ensuring consistency between corporate identity systems and GitHub access. + +### Team Sync Architecture + +```mermaid +sequenceDiagram + participant IdP as Identity Provider
(Azure AD/Okta) + participant SCIM as SCIM Bridge + participant GH as GitHub Enterprise + participant Team as GitHub Team + participant Repo as Repository + + IdP->>SCIM: User added to IdP group + SCIM->>GH: SCIM PATCH request
Add user to organization + GH->>Team: Map IdP group to team + Team->>Team: Add user to team + Team->>Repo: Grant repository access
based on team permissions + + Note over IdP,Repo: Membership sync occurs every 40 minutes + + IdP->>SCIM: User removed from IdP group + SCIM->>GH: SCIM DELETE request + GH->>Team: Remove user from team + Team->>Repo: Revoke repository access +``` + +### Configuring Team Sync + +**Prerequisites:** +- Enterprise account with EMU or SAML SSO +- SCIM provisioning enabled +- IdP group claim mapping configured +- Identity provider supports group membership + +**Setup Process:** + +1. **Enable Team Sync:** +```bash +# Organization settings → Teams → Enable team synchronization +# Requires organization owner permissions +``` + +2. **Map IdP Groups to Teams:** +```yaml +GitHub Team: engineering-backend +IdP Group: CN=Engineering-Backend,OU=Engineering,DC=company,DC=com +Sync Status: Active +Last Sync: 2024-01-15 10:30 UTC +Members Synced: 24 +``` + +3. **Configure Sync Rules:** +```json +{ + "team_sync": { + "group_id": "engineering-backend", + "provider": "azure_ad", + "group_name": "Engineering-Backend", + "sync_enabled": true, + "sync_frequency": "40_minutes", + "remove_members_not_in_group": true + } +} +``` + +### Team Sync Behavior + +**Membership Management:** + +| Action in IdP | Result in GitHub | Timing | +|---------------|------------------|--------| +| User added to group | Added to team | Next sync (≤40 min) | +| User removed from group | Removed from team | Next sync (≤40 min) | +| Group deleted | Team unchanged | Manual intervention required | +| User suspended | Removed from org | Immediate (SCIM) | +| Group renamed | Team unchanged | Manual remapping required | + +**Important Considerations:** + +1. **Manual Members:** Users manually added to synced teams are removed on next sync +2. **Team Maintainers:** Cannot manually manage membership of synced teams +3. **Nested Teams:** Child team sync is independent of parent team sync +4. **Multiple Groups:** One team can sync with one IdP group only +5. **Sync Failures:** Check audit log for `team.add_member` and `team.remove_member` events + +### Team Sync vs Manual Management + +**When to Use Team Sync:** +- Large organizations (100+ members) +- Rapid employee onboarding/offboarding +- Compliance requirements for access reviews +- Existing IdP group structure mirrors GitHub needs +- Centralized identity management mandate + +**When to Use Manual Management:** +- Small teams (< 20 members) +- Project-based temporary teams +- Cross-organizational collaboration +- Teams that don't align with IdP groups +- Contractors without IdP accounts + +## Permission Levels + +GitHub implements role-based access control (RBAC) across three scopes: repository, organization, and enterprise. Each scope has distinct permission levels with specific capabilities. + +### Repository Permission Levels + +```mermaid +graph TD + subgraph Repository Permissions + A[Read] --> B[Triage] + B --> C[Write] + C --> D[Maintain] + D --> E[Admin] + end + + A --> A1[Clone, Pull
View Issues/PRs
Fork] + B --> B1[+ Manage Issues
+ Manage PRs
+ Apply Labels] + C --> C1[+ Push Commits
+ Merge PRs
+ Create Branches] + D --> D1[+ Manage Settings
+ Manage Webhooks
+ Manage Teams] + E --> E1[+ Delete Repository
+ Transfer Ownership
+ Change Visibility] + + style A fill:#d4edda + style B fill:#c3e6cb + style C fill:#b8daff + style D fill:#f8d7da + style E fill:#f5c6cb +``` + +**Read Permission:** +- Clone and pull repository +- Open issues and comment +- Submit pull requests from forks +- View wiki pages +- Download releases +- View GitHub Actions workflows (not logs) + +**Triage Permission:** +- All Read permissions +- Manage issues (assign, label, close) +- Manage pull requests (assign, label, request reviews) +- Apply milestones +- Dismiss pull request reviews +- Lock conversations +- Hide duplicate comments + +**Write Permission:** +- All Triage permissions +- Push to protected and unprotected branches (unless restricted) +- Merge pull requests +- Edit and delete issue comments +- Delete issue attachments +- Create and edit releases +- View and cancel GitHub Actions workflow runs +- Create deployment environments + +**Maintain Permission:** +- All Write permissions +- Manage repository settings (except danger zone) +- Manage webhooks and deploy keys +- Grant team access (up to Maintain level) +- Manage branch protection rules +- Manage GitHub Pages +- Manage Actions secrets and variables +- Enable/disable Features (Wikis, Projects, Discussions) + +**Admin Permission:** +- All Maintain permissions +- Delete repository +- Change repository visibility (public/private/internal) +- Transfer repository ownership +- Manage security and analysis settings +- Grant admin access to other teams +- Manage collaborators with full permissions +- Archive repository + +### Organization Permission Levels + +**Member:** +- Create repositories (if allowed by organization settings) +- View organization members and teams +- Create teams (if allowed) +- Invite organization members +- See organization audit log (own actions only) +- Fork internal and private repositories + +**Moderator:** +- All Member permissions +- Block and unblock users +- Limit interactions for users +- Hide comments organization-wide +- Lock conversations +- Manage organization interaction limits + +**Billing Manager:** +- View billing information +- Update payment methods +- Download receipts and invoices +- Add/remove billing managers +- View organization membership (for billing purposes only) +- Cannot access repositories or organization settings + +**Owner:** +- All permissions across the organization +- Add/remove organization members +- Manage organization settings +- Configure security policies +- Manage billing and plan +- Delete organization +- Promote/demote other owners +- Access all repositories (including private) +- Configure enterprise connections + +### Enterprise Permission Levels + +**Enterprise Member:** +- Access granted organizations within enterprise +- View enterprise members list (if enabled) +- Collaborate on repositories per organization role + +**Enterprise Billing Manager:** +- View enterprise billing information +- Manage payment methods and subscriptions +- View organizations and members for billing +- Cannot access repositories or manage organizations + +**Enterprise Owner:** +- All permissions across enterprise account +- Create and manage organizations +- Configure enterprise policies +- Enforce SAML SSO and team sync +- Manage enterprise audit log and insights +- Configure IP allow lists +- Promote/demote enterprise administrators +- Remove organizations from enterprise + +### Permission Levels Matrix + +```mermaid +graph TB + subgraph Enterprise Level + E1[Enterprise Owner] + E2[Enterprise Billing Manager] + E3[Enterprise Member] + end + + subgraph Organization Level + O1[Organization Owner] + O2[Billing Manager] + O3[Moderator] + O4[Member] + end + + subgraph Repository Level + R1[Admin] + R2[Maintain] + R3[Write] + R4[Triage] + R5[Read] + end + + E1 -.->|Full Control| O1 + E1 -.->|Full Control| E2 + O1 -->|Can Grant| O2 + O1 -->|Can Grant| O3 + O1 -->|Can Grant| O4 + O1 -->|Can Grant| R1 + O4 -->|Team Based| R1 + O4 -->|Team Based| R2 + O4 -->|Team Based| R3 + O4 -->|Team Based| R4 + O4 -->|Team Based| R5 + + style E1 fill:#8b0000 + style O1 fill:#dc143c + style R1 fill:#ff6347 + style E2 fill:#4682b4 + style O2 fill:#4682b4 + style E3 fill:#90ee90 + style O4 fill:#90ee90 +``` + +### Permission Inheritance and Conflicts + +**Inheritance Rules:** + +1. **Team Membership:** User inherits all team permissions +2. **Multiple Teams:** User receives highest permission level across teams +3. **Direct Assignment:** Trumps team-based permissions +4. **Base Permissions:** Organization-wide minimum applies to all members +5. **Outside Collaborators:** Bypass base permissions (explicit only) + +**Example Scenario:** + +```yaml +User: jane@company.com + +Organization Base Permission: Read + +Team Memberships: + - engineering-team (Write on repo-a) + - security-team (Admin on repo-a) + - frontend-team (Read on repo-b) + +Direct Grants: + - repo-c: Maintain + +Effective Permissions: + - repo-a: Admin (highest from teams) + - repo-b: Read (from team) + - repo-c: Maintain (direct grant) + - repo-d: Read (base permission) +``` + +## Custom Repository Roles + +Custom repository roles enable organizations to define precise permission sets beyond the five standard levels, providing fine-grained access control tailored to specific workflows. + +### Creating Custom Roles + +**Available Permissions Categories:** + +1. **Repository Content:** + - Read repository content + - Edit repository content + - Delete repository content + +2. **Issues and Projects:** + - Read issues + - Create/edit/delete issues + - Manage issue assignments and labels + +3. **Pull Requests:** + - Read pull requests + - Create/edit/delete pull requests + - Merge pull requests + - Manage PR assignments and reviews + +4. **Repository Administration:** + - Manage branches and branch protection + - Manage webhooks and integrations + - Manage repository settings + - Manage Actions secrets and workflows + +5. **Security:** + - View vulnerability alerts + - Dismiss/resolve security alerts + - Manage security settings + +**Example Custom Role: "Security Reviewer"** + +```yaml +name: security-reviewer +base_role: read +permissions: + contents: read + issues: write + pull_requests: write + security_events: admin + actions: read + metadata: read + +description: > + Role for security team members to review code, + manage security alerts, and participate in security reviews + without write access to code. + +includes: + - View all repository content + - Create and comment on issues + - Review pull requests and request changes + - View and dismiss security alerts + - Access dependency graphs and insights + - View Actions workflow runs + +excludes: + - Push commits + - Merge pull requests + - Manage repository settings + - Create releases +``` + +**Example Custom Role: "Release Manager"** + +```yaml +name: release-manager +base_role: write +permissions: + contents: write + pull_requests: write + actions: write + packages: admin + deployments: write + metadata: read + +description: > + Role for release engineers to manage releases, + packages, and deployments without full admin access. + +includes: + - All Write permissions + - Create and publish releases + - Manage GitHub Packages + - Trigger deployment workflows + - View and manage Actions secrets (read-only) + - Cancel workflow runs + +excludes: + - Delete repository + - Manage collaborators + - Change repository visibility + - Manage webhooks +``` + +### Assigning Custom Roles + +**Via Teams:** +```bash +# Organization settings → Repository roles → Create custom role +# Team settings → Repositories → Add repository → Select custom role +``` + +**Via API:** +```bash +# Create custom role +curl -X POST \ + -H "Accept: application/vnd.github+json" \ + -H "Authorization: Bearer " \ + https://api.github.com/orgs/ORG/custom_roles \ + -d '{ + "name": "security-reviewer", + "description": "Security review role", + "base_role": "read", + "permissions": ["security_events"] + }' + +# Assign to team +curl -X PUT \ + -H "Accept: application/vnd.github+json" \ + -H "Authorization: Bearer " \ + https://api.github.com/orgs/ORG/teams/TEAM/repos/OWNER/REPO \ + -d '{"permission": "security-reviewer"}' +``` + +### Custom Role Use Cases + +**Security-Focused Roles:** +- **Security Auditor:** Read-only with security alert access +- **Vulnerability Manager:** Security admin without code write +- **Compliance Reviewer:** Read with audit log access + +**Operational Roles:** +- **CI/CD Manager:** Actions and deployments without code changes +- **Documentation Maintainer:** Write access to docs paths only (via branch rules) +- **Dependency Manager:** Packages and security updates only + +**Development Roles:** +- **Code Reviewer:** Review and comment without merge authority +- **Junior Developer:** Write with restrictions on protected branches +- **Contractor:** Limited write with approval requirements + +## Base Permissions Configuration + +Base permissions define the default access level for all organization members across repositories, establishing the minimum permission floor. + +### Base Permission Options + +**None (Default for Private Organizations):** +- Members have no access unless explicitly granted via teams +- Encourages principle of least privilege +- Requires active permission management +- Best for security-sensitive organizations + +**Read:** +- All members can view all repositories +- Promotes transparency and knowledge sharing +- Members must be granted higher permissions for contributions +- Common in open development environments + +**Write:** +- All members can contribute to all repositories +- Maximum collaboration and velocity +- Significant security implications +- Rare in enterprise environments, common in startups + +**Admin:** +- Not recommended for organizations +- All members have full repository control +- No access control or security boundaries +- Only appropriate for single-person "organizations" + +### Configuring Base Permissions + +**Organization Settings:** +```yaml +Path: Organization → Settings → Member privileges → Base permissions + +Configuration: + base_permission: "read" + members_can_create_repositories: true + repository_types_members_can_create: + - private + - internal + members_can_create_teams: false + members_can_fork_private_repos: true + outside_collaborators_block: false +``` + +**Strategic Considerations:** + +| Organization Type | Recommended Base | Rationale | +|-------------------|------------------|-----------| +| Financial Services | None | Strict compliance, explicit grants | +| Healthcare | None | HIPAA requirements, data sensitivity | +| Technology/SaaS | Read | Transparency, cross-team awareness | +| Open Source | Read | Community collaboration | +| Startup (< 50 members) | Read or Write | Velocity over process | +| Consulting Firm | None | Client confidentiality | + +### Base Permissions and Outside Collaborators + +**Key Distinction:** + +```yaml +Organization Members: + - Subject to base permissions + - Can be added to teams + - Counted in license seats + - Access via organization membership + +Outside Collaborators: + - Bypass base permissions + - Require explicit repository grants + - Not counted in license seats (with limits) + - Access via direct repository invitation + - Cannot see private repositories without explicit access +``` + +**Outside Collaborator Use Cases:** +- Contractors with limited engagement +- Partner organizations collaborating on specific projects +- Consultants performing audits or reviews +- Temporary contributors for specific features + +**Management Strategy:** + +```bash +# Audit outside collaborators +gh api /orgs/ORG/outside_collaborators \ + --jq '.[] | {login: .login, repos: .repos_url}' + +# Convert to member (if expanding role) +# Organization → People → Outside collaborators → Invite to organization + +# Remove access (if engagement ends) +gh api -X DELETE /repos/OWNER/REPO/collaborators/USERNAME +``` + +## CODEOWNERS and Automatic Review Assignment + +CODEOWNERS provides a powerful mechanism for defining code ownership boundaries, automatically assigning reviewers based on file paths, and enforcing review requirements through branch protection. + +### CODEOWNERS File Syntax + +**Location:** +- Repository root: `/.github/CODEOWNERS` +- Alternative: `/CODEOWNERS` or `/docs/CODEOWNERS` + +**Basic Syntax:** + +```bash +# Lines starting with # are comments + +# Default owner for everything (fallback) +* @org/engineering-team + +# Specific directories +/docs/ @org/documentation-team @jane-doe +/src/ @org/backend-team +/ui/ @org/frontend-team + +# Specific file types +*.js @org/javascript-team +*.go @org/golang-team +*.sql @org/database-team + +# Specific files +package.json @org/platform-leads +Dockerfile @org/devops-team +.github/workflows/ @org/cicd-team + +# Nested ownership (more specific takes precedence) +/src/payment/ @org/payment-team @org/security-team +/src/payment/encryption/ @org/security-team + +# Order matters: last matching pattern takes precedence +README.md @org/everyone +/docs/README.md @org/docs-leads +``` + +### Advanced CODEOWNERS Patterns + +**Pattern Matching:** + +```bash +# Match files at any depth +**.md @org/documentation-team + +# Match only at root +/*.yml @org/config-owners + +# Exclude pattern (not natively supported, use precedence) +/src/ @org/engineering +/src/experimental/ @org/research-team # Overrides previous + +# Multiple files same owner +*.{yml,yaml,json} @org/config-team + +# Critical paths requiring multiple approvals +/security/ @org/security-leads @org/engineering-leads @ciso +/database/migrations/ @org/dba-team @org/backend-leads +``` + +**Team vs Individual Ownership:** + +```bash +# Team ownership (preferred for resilience) +/frontend/ @org/frontend-team + +# Individual ownership (use sparingly) +/frontend/legacy/ @john-smith + +# Hybrid approach +/frontend/ @org/frontend-team +/frontend/core-framework/ @jane-doe @bob-jones @org/architecture +``` + +### Automatic Review Assignment + +**How It Works:** + +1. Developer opens pull request +2. GitHub parses CODEOWNERS for modified files +3. Teams/individuals are automatically requested as reviewers +4. Notifications sent to code owners +5. PR status checks wait for required reviews + +**Review Assignment Logic:** + +```mermaid +graph TD + A[PR Opened] --> B{Parse Changed Files} + B --> C[Match CODEOWNERS Patterns] + C --> D{Multiple Matches?} + D -->|Yes| E[Apply Most Specific Pattern] + D -->|No| F[Apply Single Match] + E --> G[Request Reviews from Teams/Users] + F --> G + G --> H{Branch Protection Enabled?} + H -->|Yes| I[Require Approval to Merge] + H -->|No| J[Reviews Optional] + I --> K{Reviews Received?} + K -->|Yes| L[Allow Merge] + K -->|No| M[Block Merge] + J --> L + + style A fill:#d4edda + style L fill:#d4edda + style M fill:#f8d7da +``` + +**Review Assignment Configuration:** + +```yaml +# Repository Settings → Code review assignment + +Enabled: true + +Assignment Method: + - Round robin: Distribute reviews evenly + - Load balance: Consider pending reviews + - Least recent reviewer: Prioritize inactive reviewers + +Team Assignment: + - Request team review: Yes + - Notify all members: No + - Auto-assign individuals: Yes + - Number to assign: 2 + - Consider unavailable: Yes (skip on vacation) + +Child Team Routing: + - Route to child teams: Yes + - Child team assignment: Random selection +``` + +### CODEOWNERS and Branch Protection + +**Integration Strategy:** + +```yaml +Branch Protection Rule: main + +Require Pull Request Reviews: + - Required approving reviews: 2 + - Dismiss stale reviews: true + - Require review from Code Owners: true # Critical setting + - Restrict dismissals: @org/engineering-leads + +Additional Requirements: + - Require status checks: true + - Require conversation resolution: true + - Include administrators: false + +Code Owner Review Behavior: + - PR cannot merge without Code Owner approval + - Code Owner review replaces generic review requirement + - Multiple owners = multiple approvals needed (if specified) +``` + +**Example Enforcement:** + +```bash +# Scenario: Change to /src/payment/api.go + +CODEOWNERS content: +/src/payment/ @org/payment-team @org/security-team + +Branch Protection: +- Require Code Owner review: Enabled +- Required reviews: 2 + +Result: +- @org/payment-team must approve (1 member minimum) +- @org/security-team must approve (1 member minimum) +- Total: 2 approvals from 2 different teams required +- Generic engineering reviews don't satisfy requirement +``` + +### CODEOWNERS Best Practices + +**Structure and Maintenance:** + +1. **Ownership Granularity:** + - Start broad, refine as needed + - Balance specificity with maintainability + - Avoid excessive individual ownership + +2. **Team-Based Ownership:** + - Prefer teams over individuals for resilience + - Ensure teams have sufficient members for coverage + - Document escalation paths + +3. **Review Coverage:** + - All code should have at least one owner + - Critical paths should have multiple owners + - Security-sensitive areas require specialized teams + +4. **Documentation:** + ```bash + # Document ownership rationale + # Backend team owns business logic + /src/services/ @org/backend-team + + # Security team required for auth changes (compliance req) + /src/auth/ @org/backend-team @org/security-team + + # Dual ownership for financial calculations (audit requirement) + /src/billing/ @org/payment-team @org/finance-team + ``` + +5. **Testing CODEOWNERS:** + ```bash + # Validate syntax + gh api repos/OWNER/REPO/codeowners/errors + + # Test ownership for specific files + gh api repos/OWNER/REPO/contents/PATH \ + --jq '.owners' + ``` + +**Anti-Patterns to Avoid:** + +```bash +# DON'T: Too many owners (review bottleneck) +/src/ @org/team1 @org/team2 @org/team3 @org/team4 @person1 @person2 + +# DO: Focused ownership +/src/ @org/backend-team + +# DON'T: Individual-only ownership (vacation/turnover risk) +/critical-path/ @john-doe + +# DO: Team with optional individual leads +/critical-path/ @org/platform-team @platform-lead + +# DON'T: Conflicting patterns (unclear precedence) +*.js @org/frontend-team +/backend/*.js @org/backend-team +/backend/api/*.js @org/api-team + +# DO: Clear hierarchical structure +/frontend/**/*.js @org/frontend-team +/backend/**/*.js @org/backend-team +``` + +## Team Maintainers vs Organization Owners + +Understanding the distinction between team maintainers and organization owners is crucial for implementing proper separation of duties and delegating administrative responsibilities. + +### Team Maintainer Role + +**Capabilities:** + +```yaml +Team Management: + - Add/remove team members (within team only) + - Edit team description and settings + - Manage team repositories (grant/revoke access) + - Delete the team + - Convert team to secret/visible + - Create child teams + +Limitations: + - Cannot access organization settings + - Cannot manage other teams (except child teams) + - Cannot view organization audit log + - Cannot manage organization billing + - Cannot create repositories (unless org setting allows) + - Cannot access repos without explicit permission +``` + +**Use Cases:** + +- Engineering team leads managing their teams +- Project managers controlling project team membership +- Department heads overseeing department teams +- Security team leads managing security groups + +**Assignment:** + +```bash +# Via UI: Team settings → Members → Promote to maintainer + +# Via API: +gh api -X PUT \ + /orgs/ORG/teams/TEAM/memberships/USERNAME \ + -f role=maintainer +``` + +### Organization Owner Role + +**Capabilities:** + +```yaml +Full Authority: + - All team maintainer permissions across ALL teams + - Organization settings and policies + - Billing and subscription management + - Create/delete repositories + - Manage organization security settings + - Access organization audit log + - Manage GitHub Apps and OAuth apps + - Transfer repository ownership + - Remove organization members + - Delete organization + +Implicit Repository Access: + - Can access all repositories (including private) + - Override branch protection for admin tasks + - Bypass required reviews for emergency fixes + - Access restricted by IP allow lists (if configured) +``` + +**Security Implications:** + +```yaml +Owner Account Protection: + - Require 2FA: Mandatory + - SAML SSO: Required for authentication + - Audit logging: All actions tracked + - IP restrictions: Apply allow lists + - Session timeout: Short duration recommended + - Device registration: Limited approved devices +``` + +### Separation of Duties + +**Delegation Strategy:** + +```mermaid +graph TD + A[Organization Owners
2-4 people] --> B[Strategic Oversight] + A --> C[Security & Compliance] + A --> D[Emergency Response] + + E[Team Maintainers
10-20 people] --> F[Team Management] + E --> G[Repository Access] + E --> H[Day-to-Day Operations] + + I[Organization Members
100s of people] --> J[Code Contribution] + I --> K[Issue Management] + I --> L[Collaboration] + + B -.->|Delegates| F + C -.->|Enforces| G + D -.->|Escalates from| H + + style A fill:#8b0000 + style E fill:#4682b4 + style I fill:#90ee90 +``` + +**Recommended Distribution:** + +| Organization Size | Owners | Team Maintainers | Ratio | +|------------------|--------|------------------|-------| +| < 50 members | 2 | 5-10 | 1:5 | +| 50-200 members | 3-4 | 10-20 | 1:15 | +| 200-1000 members | 4-6 | 20-50 | 1:50 | +| 1000+ members | 6-10 | 50+ | 1:100 | + +### Ownership Best Practices + +**Owner Account Security:** + +1. **Limited Owner Count:** + - Minimum: 2 (avoid single point of failure) + - Maximum: 5-10 (reduce attack surface) + - Principle of least privilege + +2. **Owner Selection Criteria:** + - Executive leadership (CTO, VP Engineering) + - Security leads (CISO, Security Director) + - Operations leads (Director of Infrastructure) + - Backup contacts across time zones + +3. **Protected Owner Accounts:** + ```yaml + Security Requirements: + - Hardware 2FA keys (YubiKey, etc.) + - No password-only authentication + - Dedicated "admin" accounts (not personal) + - Regular access reviews (quarterly) + - Break-glass procedures documented + ``` + +**Team Maintainer Empowerment:** + +```yaml +Delegate Authority: + Team Management: + - Add/remove members to their teams + - Create child teams for projects + - Grant repository access up to Maintain level + + Restrictions: + - Cannot grant Admin repository access + - Cannot manage organization-wide settings + - Cannot access other teams' private repos + + Governance: + - Monthly access reviews required + - Quarterly maintainer training + - Documented escalation procedures + - Audit log monitoring +``` + +**Operational Handoffs:** + +```bash +# Scenario: Engineering Lead Promotion + +Step 1: Add as Team Maintainer +gh api -X PUT /orgs/ORG/teams/engineering/memberships/USER \ + -f role=maintainer + +Step 2: Document Responsibilities +- Team: engineering-backend +- Scope: Manage team members, repository access +- Escalation: Contact @org-owners for billing/security +- Training: Complete admin onboarding + +Step 3: Grant Supporting Access +- Repository: engineering-docs (Write) +- Repository: team-tools (Maintain) +- Team: engineering-leads (Member) + +Step 4: Monitor and Review +- 30-day check-in: Review actions taken +- 90-day review: Assess effectiveness +- Ongoing: Audit log monitoring +``` + +### Emergency Access Patterns + +**Break-Glass Procedures:** + +```yaml +Scenario: Team Maintainer Unavailable + +Option 1: Backup Maintainer + - Promote secondary team member to maintainer + - Temporary elevation (document end date) + - Automated reminders to demote + +Option 2: Organization Owner Intervention + - Owner temporarily joins team + - Performs required action + - Documents in ticket/incident + - Removes self from team + +Option 3: Child Team Delegation + - Create child team for specific task + - Grant temporary maintainer to trusted member + - Delete child team after task completion +``` + +**Owner Succession Planning:** + +```yaml +Documented Process: + Current Owners: + - Primary: cto@company.com (Timezone: PST) + - Secondary: vp-eng@company.com (Timezone: EST) + - Tertiary: director-infra@company.com (Timezone: GMT) + + Backup Owners (not active): + - ciso@company.com + - director-platform@company.com + + Emergency Procedure: + 1. Contact support@github.com with enterprise account + 2. Provide verification: ticket #, domain, registered email + 3. GitHub support can promote backup owner + 4. Document incident in audit log + + Rotation Schedule: + - Annual review of owner list + - Quarterly confirmation of contact info + - Monthly break-glass procedure test +``` + +## Advanced Permission Scenarios + +### Multi-Tier Access Control + +**Scenario: Enterprise with strict compliance requirements** + +```yaml +Structure: + Enterprise: FinTech Corp + └── Organizations: + ├── production (prod.company.com) + │ ├── Base Permission: None + │ ├── Teams: 5 (security, backend, frontend, data, devops) + │ └── Repositories: 50 (all private) + │ + ├── staging (staging.company.com) + │ ├── Base Permission: Read + │ ├── Teams: 5 (mirrors production) + │ └── Repositories: 50 (mirrors production) + │ + └── development (dev.company.com) + ├── Base Permission: Write + ├── Teams: 10 (includes experimental teams) + └── Repositories: 100+ (includes prototypes) + +Access Pattern: + Junior Developer: + - development: Write (base permission) + - staging: Read (team: backend-team) + - production: None (no access) + + Senior Developer: + - development: Write (base permission) + - staging: Write (team: backend-team) + - production: Read (team: backend-team) + + Lead Developer: + - development: Admin (team: backend-leads) + - staging: Maintain (team: backend-leads) + - production: Write (team: backend-leads) + + Security Team: + - development: Custom "security-reviewer" + - staging: Custom "security-reviewer" + - production: Admin (team: security-team) +``` + +### Cross-Organization Collaboration + +**Scenario: Partner integration project** + +```yaml +Primary Organization: company-a +Partner Organization: company-b + +Repository: company-a/integration-api + Access: + - company-a/engineering: Write + - company-a/security: Admin + - partner-b-team: Write (outside collaborators) + - partner-b-lead: Maintain (outside collaborator) + +Constraints: + - Partners cannot access other company-a repositories + - CODEOWNERS requires company-a approval for core files + - Branch protection requires company-a security review + - Partners limited to integration-specific branches + +Configuration: + Branch Protection (main): + - Require company-a/security approval + - Block partner force push + - Require status checks from company-a CI + + Branch Protection (partner/*): + - Partner can force push + - Reduced review requirements + - Must pass integration tests +``` + +## Audit and Compliance + +### Permission Auditing + +**Regular Audit Procedures:** + +```bash +# Audit team membership +gh api /orgs/ORG/teams/TEAM/members --paginate \ + | jq '.[] | {login, role}' > team-audit.json + +# Audit repository access by team +gh api /orgs/ORG/teams/TEAM/repos --paginate \ + | jq '.[] | {name, permissions}' > repo-access.json + +# Find users with direct repository access (bypass teams) +gh api /repos/OWNER/REPO/collaborators \ + | jq '.[] | select(.type == "User") | {login, permissions}' + +# Audit organization owners +gh api /orgs/ORG/members?role=admin \ + | jq '.[] | .login' + +# Audit outside collaborators +gh api /orgs/ORG/outside_collaborators --paginate \ + | jq '.[] | {login, repos_url}' + +# Audit team sync status +gh api /orgs/ORG/teams --paginate \ + | jq '.[] | {name, synchronized: .synchronized}' +``` + +**Compliance Reporting:** + +```bash +# Generate quarterly access report +#!/bin/bash + +ORG="your-org" +OUTPUT="access-report-$(date +%Y-%m-%d).csv" + +echo "User,Team,Repository,Permission,Direct/Team" > $OUTPUT + +# Team-based access +for team in $(gh api /orgs/$ORG/teams --jq '.[].slug'); do + for repo in $(gh api /orgs/$ORG/teams/$team/repos --jq '.[].name'); do + for user in $(gh api /orgs/$ORG/teams/$team/members --jq '.[].login'); do + perm=$(gh api /orgs/$ORG/teams/$team/repos --jq ".[] | select(.name==\"$repo\") | .permissions | to_entries[] | select(.value==true) | .key" | tail -1) + echo "$user,$team,$repo,$perm,Team" >> $OUTPUT + done + done +done + +# Direct collaborator access +for repo in $(gh api /orgs/$ORG/repos --jq '.[].name'); do + for user in $(gh api /repos/$ORG/$repo/collaborators --jq '.[].login'); do + perm=$(gh api /repos/$ORG/$repo/collaborators/$user/permission --jq '.permission') + echo "$user,N/A,$repo,$perm,Direct" >> $OUTPUT + done +done +``` + +### Monitoring and Alerting + +**Webhook Events to Monitor:** + +```yaml +Critical Events: + - team.created + - team.deleted + - team.add_member + - team.remove_member + - member_invited + - member_removed + - org_credentials_authorized + - repository.privatized + - repository.publicized + - repository.transferred + +Security Events: + - team_add_repository + - team_remove_repository + - repository.collaborator_added + - repository.collaborator_removed + - branch_protection_rule.deleted + - organization.permission_granted +``` + +**Alert Configuration:** + +```json +{ + "alerts": [ + { + "event": "team.add_member", + "condition": "team.name matches 'production-*'", + "action": "notify_security_team", + "severity": "high" + }, + { + "event": "repository.publicized", + "action": "block_and_alert", + "severity": "critical" + }, + { + "event": "member_invited", + "condition": "role == 'admin'", + "action": "require_owner_approval", + "severity": "high" + } + ] +} +``` + +## Troubleshooting Common Issues + +### Permission Escalation Not Taking Effect + +**Symptoms:** User cannot access repository despite team membership + +**Diagnosis:** +```bash +# Check user organization membership +gh api /orgs/ORG/members/USER + +# Check team membership +gh api /orgs/ORG/teams/TEAM/memberships/USER + +# Check repository access +gh api /repos/OWNER/REPO/collaborators/USER/permission + +# Check for team sync conflicts +gh api /orgs/ORG/teams/TEAM --jq '.synchronized' +``` + +**Solutions:** +1. **Team sync delay:** Wait up to 40 minutes for IdP sync +2. **Base permissions conflict:** Check org base permission setting +3. **Repository privacy:** Ensure user can access private repos +4. **Team nesting:** Verify parent team has repository access +5. **Outside collaborator:** Convert to member for base permissions + +### CODEOWNERS Not Assigning Reviewers + +**Symptoms:** Pull requests not automatically requesting reviews + +**Diagnosis:** +```bash +# Validate CODEOWNERS syntax +gh api /repos/OWNER/REPO/codeowners/errors + +# Check file location +ls -la .github/CODEOWNERS +ls -la CODEOWNERS +ls -la docs/CODEOWNERS + +# Verify branch protection settings +gh api /repos/OWNER/REPO/branches/main/protection \ + --jq '.required_pull_request_reviews.require_code_owner_reviews' +``` + +**Solutions:** +1. **Wrong location:** Move CODEOWNERS to `/.github/` directory +2. **Syntax error:** Fix pattern matching (check for invalid characters) +3. **Team slug incorrect:** Use `@org/team-slug` not team name +4. **Branch protection disabled:** Enable "Require review from Code Owners" +5. **Team privacy:** Secret teams cannot be code owners (make visible) + +### Team Sync Failures + +**Symptoms:** Users not added/removed from teams after IdP changes + +**Diagnosis:** +```bash +# Check sync status +gh api /orgs/ORG/teams/TEAM/team-sync/group-mappings + +# View audit log for sync events +gh api /orgs/ORG/audit-log?phrase=team.add_member + +# Verify SCIM provisioning +curl https://api.github.com/scim/v2/organizations/ORG/Users \ + -H "Authorization: Bearer TOKEN" +``` + +**Solutions:** +1. **Group mapping incorrect:** Remap IdP group to team +2. **SCIM not configured:** Enable SCIM provisioning in IdP +3. **Group claim missing:** Add group claim to SAML assertion +4. **Sync disabled:** Re-enable team sync in organization settings +5. **Manual members present:** Remove manually-added members (conflict with sync) + +## References + +### Official Documentation + +- [GitHub Docs: Organizations and Teams](https://docs.github.com/en/enterprise-cloud@latest/organizations) +- [GitHub Docs: Managing Teams](https://docs.github.com/en/enterprise-cloud@latest/organizations/organizing-members-into-teams) +- [GitHub Docs: Repository Roles](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization) +- [GitHub Docs: Organization Roles](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) +- [GitHub Docs: Enterprise Roles](https://docs.github.com/en/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise) +- [GitHub Docs: CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) +- [GitHub Docs: Team Synchronization](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization) +- [GitHub Docs: Custom Repository Roles](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) + +### Related Documentation in This Series + +- [Enterprise Managed Users (EMU)](./06-enterprise-managed-users.md) - Centralized identity management and team provisioning +- [Identity and Access Management](./07-identity-access-management.md) - SAML SSO, SCIM provisioning, and authentication +- [Repository Governance](./04-repository-governance.md) - Branch protection, required reviews, and security policies + +### API References + +- [REST API: Teams](https://docs.github.com/en/rest/teams) +- [REST API: Organization Members](https://docs.github.com/en/rest/orgs/members) +- [REST API: Repository Collaborators](https://docs.github.com/en/rest/collaborators) +- [REST API: Custom Repository Roles](https://docs.github.com/en/rest/orgs/custom-roles) + +### Community Resources + +- [GitHub Community: Enterprise Best Practices](https://github.community/t/enterprise-best-practices) +- [GitHub Skills: Organization Administration](https://skills.github.com/) +- [GitHub Changelog: Team and Permission Updates](https://github.blog/changelog/) + +### Compliance and Security Frameworks + +- [SOC 2 Controls: Access Management](https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/aicpasoc2report.html) +- [NIST 800-53: Access Control](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) +- [ISO 27001: Access Management](https://www.iso.org/isoiec-27001-information-security.html) +- [CIS Controls: Account Management](https://www.cisecurity.org/controls) + +--- + +**Document Version:** 1.0 +**Last Updated:** 2024-01-15 +**Target Audience:** Enterprise administrators, security teams, compliance officers +**Skill Level:** L400 (Expert) diff --git a/docs/06-policy-inheritance.md b/docs/06-policy-inheritance.md new file mode 100644 index 0000000..459f2f1 --- /dev/null +++ b/docs/06-policy-inheritance.md @@ -0,0 +1,1181 @@ +# Policy Enforcement and Inheritance + +## Overview + +GitHub Enterprise Cloud implements a hierarchical policy enforcement model that enables enterprise administrators to establish guardrails across the entire enterprise while allowing organizational flexibility where appropriate. This three-tiered enforcement architecture—spanning enterprise, organization, and repository levels—provides the foundation for enterprise governance, security compliance, and operational consistency. + +Policy inheritance in GHEC follows a top-down cascade model where enterprise-level policies flow down to organizations and repositories. Understanding the nuances of policy enforcement states, inheritance rules, and override capabilities is critical for enterprise administrators architecting governance frameworks that balance security requirements with developer autonomy. + +The policy enforcement framework governs multiple domains including repository management, GitHub Actions, security features, collaboration tools, and member privileges. Each policy domain has specific enforcement characteristics, inheritance behaviors, and conflict resolution mechanisms that must be carefully orchestrated to achieve desired governance outcomes. + +## Policy Enforcement Model + +### Enforcement States + +GitHub Enterprise Cloud policies operate under three distinct enforcement states that determine how policies cascade through the hierarchy: + +**Enforced (No Override)** +When a policy is set to "enforced" at the enterprise level, it establishes a mandatory baseline that applies uniformly across all organizations and repositories. Organizations cannot deviate from or relax these policies—they can only apply additional restrictions. This state is used for non-negotiable security requirements, compliance mandates, and corporate standards that must be universally applied. + +Enforced policies create a compliance floor that prevents policy drift and ensures consistent security posture across the enterprise. For example, an enforced policy requiring two-factor authentication cannot be disabled by organization owners, guaranteeing authentication security enterprise-wide. + +**Allowed (Organization Choice)** +The "allowed" state grants organizations autonomy to enable or disable a capability based on their specific needs while remaining within enterprise-defined boundaries. This state is appropriate for features where business context varies across divisions, enabling organizations to self-govern within approved parameters. + +When a policy is allowed, organization owners can make independent decisions about enablement without enterprise administrator intervention. However, the enterprise retains visibility into organizational choices through audit logs and policy reports, enabling oversight without micromanagement. + +**Disabled (Enterprise Prohibition)** +A disabled policy prevents a capability from being used anywhere in the enterprise. This represents an explicit prohibition, typically driven by security concerns, licensing constraints, or strategic technology decisions. Organizations have no ability to enable disabled capabilities, creating an absolute restriction. + +Disabled policies are particularly important for managing security risk, preventing the use of deprecated features, or enforcing technology standardization. Unlike enforced policies that mandate usage, disabled policies prevent usage entirely. + +### Policy Inheritance Flow + +Policy inheritance follows a unidirectional cascade from enterprise to organization to repository, with each tier inheriting constraints from above and potentially adding additional restrictions: + +```mermaid +graph TD + A[Enterprise Policy Layer] -->|Inherits & Enforces| B[Organization Policy Layer] + B -->|Inherits & Enforces| C[Repository Settings Layer] + + A -->|Enforced| D[Mandatory: All Orgs Must Comply] + A -->|Allowed| E[Optional: Org Decides Within Bounds] + A -->|Disabled| F[Prohibited: No Org Can Enable] + + D --> G[Org Cannot Relax] + E --> H[Org Can Enable/Disable] + F --> I[Org Cannot Enable] + + G -->|Cascades| J[Repo Inherits Restriction] + H -->|If Org Enables| K[Repo Can Use Feature] + H -->|If Org Disables| L[Repo Cannot Use Feature] + I -->|Cascades| M[Repo Cannot Access Feature] + + style A fill:#6e40c9 + style B fill:#0969da + style C fill:#2da44e + style D fill:#d1242f + style E fill:#fb8500 + style F fill:#6e7781 +``` + +**Inheritance Principles:** + +1. **Restrictive Inheritance:** Child entities can only add restrictions, never relax constraints imposed by parent entities +2. **Policy Composition:** Effective policy at any level is the union of restrictions from all ancestor levels +3. **Immutable Enforcement:** Enforced enterprise policies cannot be overridden at any descendant level +4. **Visibility Cascade:** Policy visibility flows down the hierarchy, but enforcement decisions are evaluated at each tier +5. **Audit Trail Preservation:** All policy changes are logged with actor attribution and timestamps regardless of hierarchy level + +### Policy Enforcement Decision Tree + +When evaluating whether a user or system can perform an action, GitHub evaluates policies through a decision tree that considers enterprise, organization, and repository policies in sequence: + +```mermaid +graph TD + A[Action Requested] --> B{Enterprise Policy
Check} + + B -->|Policy = Disabled| C[❌ Action Denied
Enterprise Prohibition] + B -->|Policy = Enforced| D{Does Action
Comply?} + B -->|Policy = Allowed| E{Organization Policy
Check} + + D -->|No| C + D -->|Yes| E + + E -->|Org Disabled| F[❌ Action Denied
Org Prohibition] + E -->|Org Enabled| G{Repository Settings
Check} + E -->|Org Allows| G + + G -->|Repo Restricts| H{Restriction
Satisfied?} + G -->|Repo Allows| I[✅ Action Permitted] + + H -->|No| J[❌ Action Denied
Repo Restriction] + H -->|Yes| I + + I --> K[Execute Action &
Log Audit Event] + + style A fill:#0969da + style C fill:#d1242f + style F fill:#d1242f + style J fill:#d1242f + style I fill:#2da44e + style K fill:#2da44e +``` + +**Decision Flow Characteristics:** + +- **Short-Circuit Evaluation:** If enterprise policy explicitly denies an action, evaluation stops immediately without checking organization or repository policies +- **Additive Restrictions:** Each tier can add new restrictions but cannot remove restrictions from parent tiers +- **Explicit vs Implicit:** Absence of a restrictive policy is not equivalent to explicit permission—some actions require explicit enablement +- **Contextual Evaluation:** Some policies consider additional context such as repository visibility, team membership, or resource classifications + +## Enterprise-Level Policies + +Enterprise administrators control policies through the enterprise settings interface at `https://github.com/enterprises/[enterprise]/settings/policies`. These policies establish the governance framework for all member organizations. + +### Repository Management Policies + +**Repository Creation Permissions** + +Controls which organization roles can create repositories, with enforcement states determining organizational autonomy: + +- **Enforced:** Specifies exactly which roles can create repositories across all organizations (Members, None, or role-specific) +- **Allowed:** Organizations choose their own repository creation policies based on their governance models +- **Disabled:** (Not applicable—creation must be enabled for someone) + +Enterprise-enforced creation policies prevent shadow IT scenarios where uncontrolled repository proliferation creates security and compliance risks. Organizations with mature governance may receive creation autonomy, while high-risk organizations may have creation restricted to administrators. + +Best practice configuration: +- High-security environments: Enforce creation restricted to organization owners +- Standard environments: Allow organizations to decide, but require organization approval workflows +- Development-focused environments: Allow broad creation rights but enforce repository templates and security baselines + +**Repository Visibility Policies** + +Governs which repository visibility levels (public, internal, private) organizations can utilize: + +- **Enforced:** Mandates specific visibility restrictions (e.g., "no public repositories allowed") +- **Allowed:** Organizations determine appropriate visibility policies for their repositories +- **Disabled:** Prevents specific visibility levels enterprise-wide + +Internal repositories (visible to all enterprise members) are exclusive to GHEC and provide a middle ground between public and private. Enterprise policies can enforce internal-only repositories for sensitive projects while disabling public repositories to prevent data exfiltration. + +Policy considerations: +- **Public repositories:** Typically disabled for enterprises with proprietary code or regulated data +- **Internal repositories:** Enabled to facilitate inner source and cross-organization collaboration +- **Private repositories:** Always allowed, serving as the most restrictive visibility level + +**Repository Forking Policies** + +Controls whether repositories can be forked and where forks can be created: + +- **Across enterprise:** Allow forks to any organization within the enterprise +- **Within organizations:** Restrict forks to the same organization as the source repository +- **Private/internal repositories:** Separate controls for different visibility levels +- **Disabled:** Prevent forking entirely + +Fork policies balance collaboration needs against code control and intellectual property protection. Permissive fork policies enable experimentation and contribution workflows, while restrictive policies prevent unauthorized code duplication and maintain tighter access control. + +Strategic fork policy patterns: +- **Open collaboration:** Allow forking across the enterprise to encourage contribution +- **Organizational isolation:** Restrict forks to organization boundaries for audit and compliance +- **No fork zones:** Disable forking for repositories containing proprietary algorithms or regulated data + +**Repository Deletion and Transfer** + +Controls whether organization owners and repository administrators can delete repositories or transfer them between organizations: + +- **Deletion policies:** Can prevent accidental or malicious repository deletion by requiring enterprise administrator approval +- **Transfer policies:** Control whether repositories can move between organizations, affecting audit trails and access control +- **Archival requirements:** Some enterprises enforce archival before deletion to maintain historical records + +### GitHub Actions Policies + +GitHub Actions represents a significant policy domain due to its ability to execute arbitrary code, access secrets, and interact with external systems. Enterprise Actions policies provide multilayered controls for security and governance. + +**Actions Workflow Permissions** + +Controls what Actions workflows can do by default within repositories: + +- **Runner execution:** Which types of runners (GitHub-hosted, self-hosted) can be used +- **Workflow permissions:** Default token permissions for `GITHUB_TOKEN` (read-only vs write) +- **Fork pull request workflows:** Whether workflows trigger for pull requests from forks +- **Approval requirements:** Requiring approval before workflows run from new contributors + +Token permission defaults are particularly important—setting enterprise-wide read-only defaults prevents workflows from unintentionally modifying repository content or performing privileged operations without explicit permission elevation. + +**Actions and Reusable Workflows** + +Controls which Actions and reusable workflows can be used across the enterprise: + +- **Allow all actions:** No restrictions (generally inappropriate for enterprises) +- **Allow local only:** Only Actions and workflows defined within the enterprise +- **Allow select actions:** Explicitly approved list of actions from GitHub Marketplace and verified creators +- **Disable GitHub Actions:** Completely disable Actions capability + +The select actions policy requires enterprise administrators to maintain an allowlist of approved actions, typically including: +- Verified creator actions from GitHub +- Actions from trusted organizations +- Enterprise-internal actions published to private repositories + +**Actions Policy Inheritance Example** + +GitHub Actions policies cascade with specific override rules that enable defense-in-depth configuration: + +```mermaid +graph TD + A[Enterprise Actions Policy] --> B[Org A Actions Policy] + A --> C[Org B Actions Policy] + + B --> D[Repo A1 Workflow] + B --> E[Repo A2 Workflow] + C --> F[Repo B1 Workflow] + + A -->|Enforced: Only Approved Actions| G[Enterprise Allowlist] + G -->|Contains| H[actions/checkout@v4
actions/setup-node@v4
github/codeql-action/*] + + B -->|Org A Adds| I[Org-Specific Actions
org-a/deploy-action@v1] + C -->|Org B Restricts Further| J[No Self-Hosted Runners] + + D -->|Must Use Actions From| K[Enterprise Allowlist ∪ Org A Allowlist] + E -->|Must Use Actions From| K + F -->|Must Use Actions From| L[Enterprise Allowlist Only
+ No Self-Hosted] + + D -->|Workflow Runs| M[Checks:
1. Action in enterprise allowlist?
2. Action in org allowlist?
3. Runner type permitted?
4. Token permissions appropriate?] + + M -->|All Checks Pass| N[✅ Workflow Executes] + M -->|Any Check Fails| O[❌ Workflow Blocked] + + style A fill:#6e40c9 + style B fill:#0969da + style C fill:#0969da + style D fill:#2da44e + style E fill:#2da44e + style F fill:#2da44e + style N fill:#2da44e + style O fill:#d1242f +``` + +**Self-Hosted Runner Policies** + +Controls the deployment and usage of self-hosted runners: + +- **Enterprise-level runners:** Runners available to all or selected organizations +- **Organization-level runners:** Runners scoped to specific organizations +- **Repository-level runners:** Runners dedicated to individual repositories +- **Runner groups:** Logical grouping of runners with specific access controls + +Self-hosted runners introduce significant security considerations because they execute untrusted code. Enterprise policies should enforce: +- Runner group restrictions limiting which repositories can use specific runners +- Network isolation for runners processing sensitive workloads +- Ephemeral runner requirements for public repositories +- Required labels and environment segregation + +### GitHub Copilot Policies + +For enterprises with GitHub Copilot Business or Enterprise licenses, policy controls govern AI assistance capabilities: + +**Copilot Enablement** + +- **Enforced enabled:** All organization members have access to Copilot +- **Allowed:** Organizations decide whether to enable Copilot for their members +- **Disabled:** Copilot is unavailable enterprise-wide + +**Suggestions Matching Public Code** + +Controls whether Copilot can provide suggestions that match public code: + +- **Allowed:** Copilot may suggest code snippets that match publicly available code +- **Blocked:** Copilot filters out suggestions matching public code to reduce IP concerns + +Blocking public code matches reduces licensing and intellectual property risks but may decrease suggestion quality. Organizations with strict IP policies typically block public matches. + +**Content Exclusions** + +Enterprise policies can specify repositories or file patterns to exclude from Copilot processing: + +- File path patterns using glob syntax +- Entire repositories by URL +- Organization-wide exclusions + +Content exclusions prevent Copilot from learning from or suggesting code patterns from sensitive repositories, such as those containing proprietary algorithms, security implementations, or regulated data. + +### GitHub Pages Policies + +Controls the publication of static websites from repositories: + +- **Public pages:** Whether public repositories can publish Pages sites +- **Private/internal pages:** Whether private or internal repositories can publish Pages sites +- **Visibility restrictions:** Whether Pages sites must match repository visibility or can be public when repository is private +- **Custom domains:** Controls on custom domain usage and verification requirements + +Pages policies balance the value of documentation and project websites against security concerns about inadvertent data exposure. Many enterprises disable public Pages or require approval workflows for Pages publication. + +### Project Visibility Policies + +GitHub Projects (project boards) have separate visibility controls: + +- **Organization projects:** Whether organizations can create projects visible to all organization members +- **Repository projects:** Controls on repository-level project visibility +- **Enterprise-wide projects:** Availability of enterprise-level project tracking + +Projects can contain sensitive planning information, making visibility controls important for enterprises with confidential product roadmaps or competitive intelligence concerns. + +### Member Privilege Policies + +Enterprise policies controlling member capabilities and permissions: + +**Repository Invitations** + +- **Who can invite:** Controls which roles can invite external collaborators to organization repositories +- **Approval requirements:** Whether external invitations require organization owner approval +- **Domain restrictions:** Limits invitations to specific email domains + +External collaborator invitations represent a significant security boundary because they grant repository access to users outside the enterprise. Enforcing approval workflows ensures appropriate review before expanding the trust boundary. + +**Team Creation Permissions** + +- **Enforced:** Specifies who can create teams (members vs organization owners only) +- **Allowed:** Organizations determine their own team creation policies +- **Disabled:** (Not applicable—team creation must be permitted for administrators) + +Liberal team creation policies enable self-organization and agile structures, while restrictive policies maintain tighter organizational control and reduce shadow IT risks. + +**Profile Name and Email Visibility** + +- **Enforced public:** Member profiles must be visible to the public +- **Allowed private:** Members can choose to make profiles private +- **Enterprise-only visibility:** Profiles visible only within the enterprise + +Profile visibility policies affect collaboration discovery and organizational transparency. Enterprises concerned about OSINT reconnaissance may enforce private profiles to reduce external visibility of organizational structure. + +## Organization-Level Policies + +Organizations inherit enterprise policies and can add additional restrictions within the boundaries established by enterprise settings. Organization policies are configured at `https://github.com/organizations/[org]/settings`. + +### Policy Delegation Model + +Organization owners exercise delegated authority from the enterprise, with their policy autonomy constrained by enterprise enforcement: + +**Inherited Enforcement** +- Enforced enterprise policies appear in organization settings but cannot be modified +- Organization settings UI indicates policies enforced at enterprise level with explanatory text +- Attempts to relax enterprise-enforced policies through API return authorization errors + +**Organizational Autonomy** +- Where enterprise policies are "allowed," organizations have full policy-setting authority +- Organizations can enforce policies that enterprise leaves optional +- Organizations can disable features that enterprise allows +- Organizations cannot enable features that enterprise disables + +**Additive Restriction Pattern** +Organizations commonly implement organization-specific restrictions beyond enterprise baselines: +- Enterprise allows public repositories → Organization disables public repositories for specific security concerns +- Enterprise allows all Actions → Organization restricts to approved subset relevant to their tech stack +- Enterprise allows member repository creation → Organization requires approval workflow + +### Organization Policy Domains + +**Base Permissions** + +Default repository permissions for organization members: +- **None:** Members have no default access to repositories +- **Read:** Members can read all organization repositories +- **Write:** Members can read and write to all organization repositories +- **Admin:** Members have administrative rights to all repositories (rarely used) + +Base permissions establish the default access level before team-based or individual permissions are applied. Security-conscious organizations typically set base permissions to "none" and use explicit team memberships for access control. + +**Default Repository Permissions** + +Template settings applied to newly created repositories: +- Default visibility (private, internal, public) within enterprise constraints +- Default branch name (main, master, etc.) +- Automatically created repositories include standard files (README, .gitignore, LICENSE) +- Default repository permission level for organization members + +**Admin Repository Permissions** + +Controls what repository administrators can do: +- Force push to protected branches +- Delete or transfer repositories +- Change repository visibility +- Manage webhooks and integrations + +These controls limit the privileges of repository administrators, preventing dangerous operations even for users with admin role assignments. + +**Third-Party Application Access** + +Controls integration of OAuth applications with organization resources: +- **Allowed applications:** Explicitly approved OAuth apps +- **Denied applications:** Blacklisted applications +- **Approval required:** Whether applications require organization owner approval before accessing organization data + +Many enterprises maintain strict application access control to prevent data exfiltration through third-party integrations. Unapproved applications cannot access organization resources even if individual users authorize them. + +**Organization Secrets** + +Encrypted secrets available to Actions workflows in organization repositories: +- Organization secrets can be scoped to all repositories or selected repositories +- Secrets inherit access control from organization and repository policies +- Secret rotation and audit logging are critical for compliance + +Organization secrets enable centralized credential management for CI/CD workflows without exposing credentials in repository code or individual repository secrets. + +## Repository-Level Settings + +Repository settings represent the lowest tier of policy hierarchy, where policies from enterprise and organization levels converge with repository-specific configurations. + +### Repository Setting Categories + +**Branch Protection Rules** + +Repository-specific access controls for branches: +- Required pull request reviews before merging +- Required status checks (CI/CD pipelines) before merging +- Required conversation resolution before merging +- Restrictions on who can push to matching branches +- Required linear history +- Required deployments to specific environments before merging + +Branch protection rules implement repository-specific workflows while operating within organization and enterprise constraints. For example, even with branch protection rules, enterprise-required status checks must still pass. + +**Collaboration Settings** + +Repository-specific collaboration configuration: +- Features enabled (wikis, issues, projects, discussions) +- Merge button options (merge commits, squash, rebase) +- Automatically delete head branches after pull request merges +- Pull request update methods + +These settings customize repository workflow while enterprise and organization policies may restrict available options. + +**Security and Analysis** + +Security feature enablement for the repository: +- Dependency graph +- Dependabot alerts +- Dependabot security updates +- Dependabot version updates +- Secret scanning +- Code scanning + +Repository owners can enable these features if organization and enterprise policies permit. Some enterprises enforce security features at organization or enterprise level to ensure uniform security posture. + +**Actions Repository Settings** + +Repository-specific Actions configuration within organization and enterprise constraints: +- Actions permissions (which actions and workflows can run) +- Workflow permissions (default `GITHUB_TOKEN` permissions) +- Fork pull request workflows from external contributors +- Required approval for workflows + +Even with repository-level settings, Actions must still comply with organization and enterprise Actions policies. + +### Repository Setting Inheritance + +Repository settings combine inherited policies with repository-specific configuration: + +1. **Enterprise policies** flow down as immutable constraints +2. **Organization policies** add additional restrictions within enterprise boundaries +3. **Repository settings** customize behavior within the effective policy framework + +Repositories cannot violate policies from above, but can implement additional restrictions. For example: +- Enterprise allows public repositories → Organization allows public → Repository chooses private (more restrictive) +- Enterprise requires Actions approval → Repository inherits requirement (cannot disable) +- Organization sets base permission "read" → Repository can grant team-specific write access (within established base) + +## Policy Conflict Resolution + +When policies at different hierarchy levels interact, GitHub employs specific resolution mechanisms to determine effective policy: + +### Resolution Principles + +**Principle 1: Most Restrictive Wins** + +When policies conflict, the most restrictive policy takes precedence: +- Enterprise disables feature → Organization/repository cannot enable +- Organization restricts access → Repository cannot expand access beyond restriction +- Multiple restrictions apply → All restrictions must be satisfied + +Example: If enterprise policy limits Actions to approved list, organization further restricts to subset, and repository attempts to use action outside organization subset, the action is blocked. + +**Principle 2: Explicit Over Implicit** + +Explicit policy statements override implicit defaults: +- Explicit denial at any level overrides implicit permission +- Explicit permission requirements aggregate across levels +- Absence of explicit policy at higher level allows lower level control + +Example: If enterprise does not explicitly control repository visibility, organization policy determines available options. If organization explicitly restricts visibility, repository must comply regardless of enterprise settings. + +**Principle 3: Enforcement State Hierarchy** + +Enterprise enforcement state determines organizational autonomy: +- **Enforced → Allowed:** Organization cannot relax but can further restrict +- **Enforced → Enforced:** Organization can match or exceed restriction +- **Allowed → Any:** Organization has full control within allowed boundaries +- **Disabled → Any:** Capability unavailable regardless of lower-tier settings + +**Principle 4: Scope-Based Precedence** + +When policies apply to different scopes, narrower scope policies apply within broader constraints: +- Enterprise-wide policy establishes boundary +- Organization policy applies within enterprise boundary +- Repository policy applies within organization boundary + +### Conflict Scenarios + +**Scenario 1: Visibility Conflict** + +- Enterprise: Allows public, internal, and private repositories +- Organization: Disables public repositories +- Repository: Attempts to change visibility to public + +**Resolution:** Repository visibility change is denied because organization policy explicitly disables public repositories, even though enterprise allows it. Organization policy is more restrictive and takes precedence within that organization. + +**Scenario 2: Actions Workflow Conflict** + +- Enterprise: Enforces approved Actions list containing `actions/checkout@v4` +- Organization: Further restricts to specific actions, excluding `actions/checkout@v4` +- Repository: Workflow attempts to use `actions/checkout@v4` + +**Resolution:** Workflow execution is blocked because organization policy explicitly excludes the action. Both enterprise and organization policies must be satisfied, and organization policy is more restrictive. + +**Scenario 3: Repository Creation Conflict** + +- Enterprise: Enforced policy allowing only organization owners to create repositories +- Organization: Attempts to allow all members to create repositories + +**Resolution:** Organization setting is overridden by enterprise enforcement. Only organization owners can create repositories. The organization setting may appear in UI but is ineffective due to enterprise enforcement. + +**Scenario 4: Team Permission Conflict** + +- Enterprise: Allows organizations to set base permissions +- Organization: Sets base permission to "none" +- Team: Granted "write" permission to specific repository +- User: Member of team and organization + +**Resolution:** User receives "write" permission to the repository because team-specific permissions are additive to base permissions. Base permission "none" establishes the floor, and team permission elevates access for team members. + +### Policy Precedence Matrix + +| Enterprise Policy | Organization Policy | Effective Result | +|------------------|---------------------|------------------| +| Enforced (Required) | Any | Enterprise policy applies, organization cannot change | +| Allowed | Enabled | Feature available, organization choice respected | +| Allowed | Disabled | Feature unavailable in organization | +| Allowed | Further Restricted | Organization restrictions apply within enterprise boundary | +| Disabled (Prohibited) | Any | Feature unavailable enterprise-wide, organization cannot enable | + +### Conflict Detection and Prevention + +**Policy Preview and Validation** + +Before enforcing enterprise policies, administrators should: +1. **Audit current state:** Survey existing organization policies to identify conflicts +2. **Impact analysis:** Identify organizations and repositories affected by policy changes +3. **Communication plan:** Notify organization owners of upcoming policy enforcements +4. **Phased rollout:** Apply policies to pilot organizations before enterprise-wide enforcement +5. **Validation period:** Monitor audit logs for policy violations and unexpected behaviors + +**Conflict Notification** + +GitHub provides visibility into policy conflicts: +- Organization settings UI displays enterprise-enforced policies with explanatory text +- API responses include error details when operations violate enterprise policies +- Audit logs record policy enforcement blocks with context about the blocking policy + +**Resolution Tools** + +Enterprise administrators have tools to identify and resolve conflicts: +- **Enterprise policy report:** Dashboard showing organization compliance with enterprise policies +- **Organization policy export:** API endpoints to retrieve organization policy configurations +- **Audit log queries:** Filter audit events by policy-related actions to identify friction points + +## Policy Change Auditing + +Comprehensive audit logging of policy changes is critical for compliance, security investigations, and operational accountability. + +### Enterprise Audit Log + +The enterprise audit log (`https://github.com/enterprises/[enterprise]/settings/audit-log`) records all policy-related events: + +**Policy Change Events** + +Events logged when enterprise policies are modified: +- `policy.update`: Enterprise policy configuration changed +- `policy.enable`: Previously disabled policy enabled +- `policy.disable`: Policy disabled enterprise-wide +- `policy.enforcement.update`: Policy enforcement state changed (enforced/allowed/disabled) + +Each event includes: +- **Actor:** Enterprise owner who made the change +- **Timestamp:** When the change occurred (UTC) +- **Policy domain:** Which policy area was affected (actions, repository, pages, etc.) +- **Before/after values:** Old and new policy configurations +- **IP address:** Source IP of the administrative action +- **User agent:** Browser or API client used for the change + +**Organization Policy Events** + +Events logged when organization policies are modified within enterprise boundaries: +- `org.update_policy`: Organization policy changed +- `org.policy_compliance`: Organization policy brought into compliance with enterprise enforcement +- `org.policy_violation`: Attempted policy change blocked by enterprise enforcement + +**Repository Policy Events** + +Repository-level policy changes are logged in organization audit logs: +- `repo.update`: Repository settings changed +- `protected_branch.create`: Branch protection rule created +- `protected_branch.update`: Branch protection rule modified +- `repository_visibility.update`: Repository visibility changed + +### Audit Log Retention and Export + +**Retention Policies** + +- **Enterprise audit log:** 180-day retention by default for GHEC +- **Organization audit log:** 180-day retention for organizations within GHEC enterprise +- **Extended retention:** Available through audit log streaming to SIEM systems + +**Export and Streaming** + +Enterprise administrators can export audit logs for long-term retention and analysis: + +- **Manual export:** Download audit log data as JSON or CSV from enterprise settings +- **API access:** Retrieve audit log events programmatically via REST API +- **Audit log streaming:** Real-time streaming to SIEM platforms (Splunk, Azure Event Hubs, Amazon S3, Datadog, etc.) + +Streaming configuration: +``` +Enterprise Settings → Audit log → Streaming +→ Configure destination endpoint +→ Set up authentication (tokens, connection strings) +→ Enable streaming for continuous log delivery +``` + +### Compliance Monitoring + +**Policy Compliance Dashboard** + +Enterprise administrators should implement monitoring for policy compliance: + +1. **Policy drift detection:** Regular scans comparing current policies against baseline configurations +2. **Violation alerts:** Notifications when policy enforcement blocks administrative actions +3. **Usage reports:** Analytics on policy-controlled feature usage (Actions, Pages, external collaborators) +4. **Anomaly detection:** Identification of unusual policy changes or access patterns + +**Audit Query Patterns** + +Common audit log queries for policy monitoring: + +**Recent policy changes:** +``` +action:policy.* +created:>YYYY-MM-DD +``` + +**Actions policy violations:** +``` +action:workflows.completed +conclusion:failure +policy_violation:true +``` + +**Repository visibility changes:** +``` +action:repository_visibility.update +``` + +**External collaborator additions:** +``` +action:org.add_outside_collaborator +``` + +**Enterprise policy override attempts:** +``` +action:org.update_policy +org:[organization] +result:failure +``` + +### Compliance Reporting + +Organizations subject to regulatory compliance (SOC 2, ISO 27001, FedRAMP, etc.) require documented evidence of policy enforcement: + +**Compliance Artifacts** + +- **Policy configuration exports:** Documentation of current enterprise and organization policies +- **Change management records:** Audit log evidence of policy changes with approval workflows +- **Violation reports:** Documented instances of policy enforcement blocks +- **Access reviews:** Regular attestation that policies are correctly configured and enforced + +**Compliance Automation** + +Integrate GitHub audit logs with compliance automation platforms: +- Export policy configurations to infrastructure-as-code repositories +- Automated policy validation against compliance frameworks +- Integration with GRC (Governance, Risk, Compliance) platforms +- Continuous compliance monitoring dashboards + +## Advanced Policy Patterns + +### Defense in Depth Policy Architecture + +Implement layered policy controls where multiple independent policy mechanisms protect against the same risk: + +**Example: Code Quality Enforcement** + +- **Enterprise layer:** Require GitHub Advanced Security license for all organizations +- **Organization layer:** Enable required status checks for all repositories +- **Repository layer:** Configure branch protection requiring code scanning and test passage +- **Workflow layer:** Implement rulesets enforcing required workflows for CI/CD + +Each layer provides independent enforcement, ensuring that failure or misconfiguration at one layer does not eliminate all protections. + +### Context-Aware Policy Enforcement + +Design policies that adapt based on repository characteristics: + +**Repository Classification-Based Policies** + +- **Public repositories:** Strictest policies including required code review, security scanning, and restricted Actions +- **Internal repositories:** Moderate policies balancing security with collaboration +- **Private repositories:** Flexible policies for early-stage development with security reviews before promoting to internal/public + +Implement classification through: +- Repository topics (e.g., `tier-1-security`, `compliance-required`) +- Organization membership (critical organizations vs general development) +- Repository templates with predefined security configurations + +### Policy as Code + +Manage enterprise and organization policies using infrastructure-as-code principles: + +**Terraform GitHub Provider** + +```hcl +resource "github_enterprise_policy" "actions_policy" { + enterprise_id = data.github_enterprise.main.id + + actions_policy { + allowed_actions = "selected" + enabled_repositories = "all" + + allowed_actions_config { + github_owned_allowed = true + verified_allowed = true + patterns_allowed = [ + "actions/checkout@*", + "actions/setup-node@*", + "github/codeql-action/*" + ] + } + } +} +``` + +**Benefits:** +- Version control for policy configurations +- Code review processes for policy changes +- Automated policy deployment with CI/CD +- Drift detection comparing actual state to desired state + +### Policy Testing and Validation + +Before enforcing enterprise-wide policies, validate impact through controlled testing: + +**Policy Simulation** + +1. **Test organization:** Create dedicated organization for policy testing +2. **Mirror production:** Configure test organization with representative repositories +3. **Apply policy:** Enable candidate policy in test organization +4. **Validate workflows:** Verify that legitimate workflows function correctly +5. **Measure impact:** Collect metrics on workflow success rates, developer friction +6. **Iterate:** Refine policy based on feedback before enterprise rollout + +**Canary Deployment** + +Roll out enterprise policies progressively: +1. Enforce policy in low-risk organizations first +2. Monitor audit logs for policy violations and workarounds +3. Gather feedback from organization owners and developers +4. Address issues and adjust policy configuration +5. Gradually expand enforcement to additional organizations +6. Complete enterprise-wide rollout after validation + +## Key Policy Areas Deep Dive + +### Repository Creation and Visibility + +**Strategic Considerations** + +Repository creation and visibility policies affect organizational collaboration patterns, security boundaries, and intellectual property protection. These policies must balance: + +- **Innovation velocity:** Liberal creation policies enable experimentation +- **Governance overhead:** Excessive repositories increase management burden +- **Security risk:** Public repositories can inadvertently expose sensitive data +- **Collaboration needs:** Internal repositories facilitate inner source practices + +**Enterprise Policy Options** + +``` +Repository Creation: +├── Enforced: Members can create [Public/Internal/Private] +├── Enforced: Only organization owners can create +├── Allowed: Organizations determine creation permissions +└── Custom: Role-based creation limits + +Repository Visibility: +├── Enforced: No public repositories +├── Enforced: Only internal and private repositories +├── Allowed: Organizations control visibility options +└── Enforced: Public requires approval workflow +``` + +**Implementation Best Practices** + +High-security enterprises typically: +- Disable public repository creation to prevent data exfiltration +- Allow internal repositories for cross-organization collaboration +- Enforce private repositories as default for new creations +- Require organization owner approval for visibility changes to public/internal + +Development-focused enterprises may: +- Allow all members to create private and internal repositories +- Permit public repositories for open source projects with approval workflows +- Use repository templates to standardize security configurations +- Monitor repository creation patterns for anomalies + +### Repository Forking Policies + +**Forking Security Model** + +Repository forks create complete copies of repository content including commit history, branches, and tags. Fork policies control: + +- **Data duplication:** Whether repository content can be copied to other locations +- **Access boundary expansion:** Whether users can gain persistent access to repository content beyond original access grants +- **Contribution workflows:** Whether external contributors can use fork-based pull request workflows + +**Policy Configurations** + +``` +Private/Internal Repository Forking: +├── Allowed in all enterprise organizations +│ └── Users can fork to any organization where they have membership +├── Allowed in same organization only +│ └── Forks restricted to source repository's organization +├── Allowed in same organization hierarchy only +│ └── Forks permitted within nested organizational structures +└── Disabled + └── No forking permitted for private/internal repositories + +Public Repository Forking: +├── Allowed to any user (standard GitHub behavior) +├── Allowed to enterprise members only +└── Disabled +``` + +**Strategic Fork Policy Patterns** + +**Open Collaboration Model:** +- Allow forking across enterprise organizations +- Enables engineers to contribute to any internal project +- Facilitates inner source development practices +- Requires strong repository access governance + +**Isolated Organization Model:** +- Restrict forking to same organization +- Maintains organizational ownership boundaries +- Reduces audit complexity for regulated environments +- May limit cross-team collaboration + +**No Fork Model:** +- Disable forking entirely for sensitive repositories +- Requires branch-based contribution workflows +- Maximum control over code distribution +- Appropriate for IP-sensitive codebases + +### GitHub Actions Permissions + +**Token Permission Model** + +GitHub Actions workflows execute with a `GITHUB_TOKEN` that provides authenticated access to repository resources. Enterprise policies control default token permissions: + +**Permission Scopes:** +- `actions`: Manage Actions workflows and artifacts +- `checks`: Create and update check runs +- `contents`: Read/write repository contents +- `deployments`: Manage deployment statuses +- `issues`: Read/write issues and comments +- `packages`: Publish and manage packages +- `pull_requests`: Read/write pull requests +- `repository_projects`: Manage project boards +- `security_events`: Read/write security alerts +- `statuses`: Read/write commit statuses + +**Default Permission Strategies** + +**Read-Only Default (Recommended):** +``` +Enterprise Policy: Default GITHUB_TOKEN permissions = read-only +→ Organization: Inherits read-only default +→ Repository: Workflows must explicitly request write permissions +→ Workflow: Elevates permissions for specific jobs only +``` + +Benefits: +- Prevents accidental repository modifications +- Reduces impact of compromised workflows +- Forces explicit permission requirements in workflow files +- Enables security review of permission elevations + +**Write Default (Legacy, Less Secure):** +``` +Enterprise Policy: Default GITHUB_TOKEN permissions = write +→ Organization: Inherits write default +→ Repository: All workflows have write access by default +→ Workflow: Can implicitly modify repository without explicit permission +``` + +Risks: +- Malicious or compromised Actions can modify repository +- Pull request workflows from forks can potentially write to repository +- No explicit security review trigger for write operations +- Violates principle of least privilege + +**Recommended Enterprise Configuration:** + +``` +Actions Permissions: +├── Default workflow permissions: read +├── Allow workflows to approve pull requests: disabled +├── Fork pull request workflows: require approval for all outside collaborators +└── Required workflows: enforce security scanning and compliance checks + +Allowed Actions: +├── Allow actions created by GitHub: enabled +├── Allow actions by verified creators: enabled +├── Allow specified actions and reusable workflows: +│ ├── actions/checkout@v4 +│ ├── actions/setup-node@v4 +│ ├── actions/cache@v3 +│ ├── github/codeql-action/* +│ └── [enterprise-org]/* +└── Block actions from untrusted sources +``` + +### GitHub Copilot Policies + +**Enterprise Copilot Governance** + +GitHub Copilot policies control AI-assisted development capabilities across the enterprise: + +**Enablement Control:** +- **Enforced enabled:** Mandate Copilot for all developers to standardize AI-assisted workflows +- **Allowed:** Organizations decide Copilot adoption based on team readiness +- **Disabled:** Prohibit Copilot enterprise-wide due to IP concerns or policy restrictions + +**Public Code Matching Policy:** + +Copilot can suggest code that matches publicly available code. Enterprise policy options: + +- **Allow matching:** Copilot may suggest code similar to public repositories + - **Benefit:** Higher quality, more diverse suggestions + - **Risk:** Potential licensing and IP concerns if public code has incompatible licenses + +- **Block matching:** Filter suggestions matching public code + - **Benefit:** Reduced IP and licensing risk + - **Risk:** Suggestion quality may decrease + +**Content Exclusion Patterns** + +Enterprises can exclude specific repositories or file patterns from Copilot processing: + +``` +Exclusion Configuration: +├── Repository exclusions: +│ ├── https://github.com/[enterprise]/proprietary-algorithm +│ ├── https://github.com/[enterprise]/security-implementations +│ └── https://github.com/[enterprise]/regulated-data-processing +│ +├── File pattern exclusions: +│ ├── **/*.key (cryptographic keys) +│ ├── **/*.pem (certificates) +│ ├── **/secrets/** (credential directories) +│ ├── **/config/production/** (production configurations) +│ └── **/proprietary/** (proprietary code directories) +│ +└── Organization-wide exclusions: + └── https://github.com/[enterprise]/[high-security-org]/* +``` + +**Strategic Copilot Adoption Patterns** + +**Full Adoption Model:** +- Enable Copilot for all developers +- Allow public code matching +- Minimal content exclusions (only sensitive secrets/keys) +- Appropriate for enterprises prioritizing developer velocity + +**Controlled Adoption Model:** +- Allow organizations to opt-in to Copilot +- Block public code matching +- Exclude repositories with proprietary algorithms +- Appropriate for enterprises with moderate IP concerns + +**Restricted Adoption Model:** +- Disable Copilot or severely restrict enablement +- Comprehensive content exclusions +- Enhanced monitoring of AI-generated code +- Appropriate for highly regulated industries (finance, healthcare, defense) + +## Cross-Hierarchy Policy Scenarios + +### Scenario 1: Implementing Zero-Trust Repository Access + +**Objective:** Enforce zero-trust principle where no implicit repository access is granted + +**Enterprise Policies:** +- Enforce base repository permission: None +- Enforce repository creation: Organization owners only +- Enforce external collaborator invitations: Require approval +- Enforce Actions default permissions: Read-only + +**Organization Policies:** +- Disable forking to prevent persistent access after team membership removal +- Require team-based access grants (no individual collaborator additions) +- Enable SAML SSO enforcement for all repository access +- Implement just-in-time access using temporary team memberships + +**Repository Settings:** +- Branch protection requiring pull request reviews +- Required status checks enforcing security scans +- Signed commits required +- Deployment branches restricted to specific protected branches + +**Result:** Access is explicitly granted through team memberships, time-boxed when possible, and monitored through comprehensive audit logging. No user has repository access by default. + +### Scenario 2: Inner Source Enablement with IP Protection + +**Objective:** Enable cross-organization contribution while protecting intellectual property + +**Enterprise Policies:** +- Allow internal repository creation +- Disable public repository creation +- Allow forking within enterprise only +- Enforce Actions to approved list (prevent data exfiltration via malicious Actions) + +**Organization Policies:** +- Encourage internal repository visibility for non-sensitive projects +- Require maintainer approval for external organization contributors +- Implement repository classification using topics (public-ok, internal-only, private-only) +- Enable required workflows for license compliance checks + +**Repository Settings:** +- CODEOWNERS files requiring approval from IP-aware maintainers +- Branch protection requiring status checks from license scanning tools +- Contribution guidelines documenting acceptable contribution types +- Templates for contributors to certify compliance with contribution policies + +**Result:** Developers across organizations can discover and contribute to internal projects while automated checks prevent inadvertent exposure of sensitive IP or incompatible licensing. + +### Scenario 3: Regulated Environment Compliance + +**Objective:** Meet SOC 2, ISO 27001, and FedRAMP compliance requirements + +**Enterprise Policies:** +- Enforce GitHub Advanced Security for all organizations +- Enforce secret scanning (no bypass) +- Enforce two-factor authentication +- Disable public and internal repositories (private only) +- Enforce Actions approval for workflows from new contributors +- Enforce audit log streaming to compliance SIEM + +**Organization Policies:** +- Require organization SAML SSO with IdP-based MFA +- Disable repository deletion (require archival through compliance workflow) +- Enforce repository naming conventions for classification +- Require organization-level secrets rotation every 90 days + +**Repository Settings:** +- Branch protection on all branches containing production code +- Require linear history (no merge commits to maintain audit trail) +- Required code scanning with zero high-severity vulnerabilities +- Deployment protection rules requiring manual approval for production environments +- Required workflows enforcing compliance scanning tools + +**Result:** Comprehensive defense-in-depth security controls with audit trails meeting regulatory requirements. Policy enforcement ensures no single misconfiguration can violate compliance controls. + +## Related Documentation + +Understanding policy inheritance requires familiarity with the broader GitHub Enterprise Cloud governance architecture: + +### Core Hierarchy and Governance + +- **[Enterprise Hierarchy](01-enterprise-hierarchy.md):** Foundational understanding of GHEC organizational structure and how enterprise, organization, and repository levels relate. Essential context for understanding policy cascade. + +- **[Organization Strategies](02-organization-strategies.md):** Organization design patterns that influence policy requirements. Multi-organization enterprises need different policy strategies than single-organization structures. + +- **[Teams and Permissions](05-teams-permissions.md):** How policies interact with team-based access control. Team permissions operate within the effective policy framework established by enterprise and organization policies. + +### Identity and Access + +- **[Identity and Access Management](03-identity-access-management.md):** Authentication and authorization mechanisms that policies enforce. Policies govern who can authenticate and what they can do after authentication. + +- **[Enterprise Managed Users](04-enterprise-managed-users.md):** EMU-specific policy considerations. EMU environments have additional policy controls and restrictions beyond standard GHEC. + +### Security and Compliance + +- **[Repository Governance](07-repository-governance.md):** Repository-level governance mechanisms including rulesets and branch protection that implement policy requirements at the repository level. + +- **[Security and Compliance](08-security-compliance.md):** Security feature policies, compliance frameworks, and audit logging that enable policy enforcement validation and compliance demonstration. + +### Architecture and Best Practices + +- **[Best Practices and Well-Architected Framework](09-best-practices-waf.md):** Policy design patterns aligned with GitHub WAF principles. How to architect policy frameworks that scale across large enterprises. + +- **[Reference Architecture](10-reference-architecture.md):** Example policy architectures for common enterprise scenarios with Mermaid diagrams illustrating policy flows. + +## References + +### Official GitHub Documentation + +**Enterprise Policy Management** +- [Enforcing Policies in Your Enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/enforcing-policies) - Comprehensive guide to all enterprise policy domains +- [About Enterprise Policies](https://docs.github.com/en/enterprise-cloud@latest/admin/enforcing-policies/about-enterprise-policies) - Policy model and enforcement fundamentals +- [Enforcing Repository Management Policies](https://docs.github.com/en/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise) - Repository-specific policy controls + +**GitHub Actions Policies** +- [Enforcing GitHub Actions Policies](https://docs.github.com/en/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise) - Actions policy configuration and inheritance +- [Managing GitHub Actions Settings](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-github-actions-for-your-enterprise/managing-github-actions-settings-for-your-enterprise) - Enterprise Actions management +- [Security Hardening for GitHub Actions](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) - Actions security best practices + +**Organization Settings** +- [Managing Organization Settings](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings) - Organization-level policy configuration +- [Managing Security Settings for Your Organization](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/managing-security-settings-for-your-organization) - Organization security policies +- [Organization Base Permissions](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization) - Default access controls + +**Audit and Compliance** +- [Reviewing Audit Logs](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise) - Audit log structure and querying +- [Streaming Audit Logs](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise) - Real-time audit log export +- [Audit Log Events](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise) - Complete event reference + +**GitHub Copilot Policies** +- [Managing GitHub Copilot in Your Organization](https://docs.github.com/en/enterprise-cloud@latest/copilot/managing-copilot/managing-copilot-for-your-enterprise) - Enterprise Copilot configuration +- [Configuring Content Exclusions](https://docs.github.com/en/enterprise-cloud@latest/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise) - Content exclusion patterns + +**Security Features** +- [GitHub Advanced Security](https://docs.github.com/en/enterprise-cloud@latest/get-started/learning-about-github/about-github-advanced-security) - GHAS features and licensing +- [Secret Scanning](https://docs.github.com/en/enterprise-cloud@latest/code-security/secret-scanning) - Secret detection policies +- [Code Scanning](https://docs.github.com/en/enterprise-cloud@latest/code-security/code-scanning) - Automated security analysis + +### GitHub Resources and Learning + +**Enterprise Administration** +- [GitHub Enterprise Cloud Documentation](https://docs.github.com/en/enterprise-cloud@latest) - Complete GHEC documentation +- [GitHub Admin Portal](https://resources.github.com/learn/pathways/administration-governance/) - Learning paths for enterprise administrators +- [GitHub Skills](https://skills.github.com/) - Hands-on tutorials and exercises + +**Best Practices** +- [GitHub Enterprise Best Practices](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/best-practices-for-enterprises) - Official recommendations +- [GitHub Security Best Practices](https://docs.github.com/en/code-security/getting-started/github-security-features) - Security hardening guidance + +**API References** +- [GitHub REST API - Policies](https://docs.github.com/en/rest/enterprise-admin) - Programmatic policy management +- [GitHub GraphQL API](https://docs.github.com/en/graphql) - Advanced queries for policy data +- [Terraform GitHub Provider](https://registry.terraform.io/providers/integrations/github/latest/docs) - Infrastructure-as-code for policies + +### Compliance and Standards + +**Regulatory Frameworks** +- [SOC 2 Compliance](https://github.com/security) - GitHub's SOC 2 Type II certification +- [FedRAMP Authorization](https://marketplace.fedramp.gov/products/github-enterprise-cloud) - Government compliance +- [ISO/IEC 27001](https://github.com/security) - Information security management + +**Industry Standards** +- [CIS Benchmarks for GitHub](https://www.cisecurity.org/) - Security configuration guidelines +- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) - Risk management framework +- [OWASP Secure Coding Practices](https://owasp.org/) - Application security guidelines diff --git a/docs/07-repository-governance.md b/docs/07-repository-governance.md new file mode 100644 index 0000000..c52ed9b --- /dev/null +++ b/docs/07-repository-governance.md @@ -0,0 +1,1492 @@ +# Repository Governance + +**Level:** L400 (Expert) +**Objective:** Master repository settings, rulesets, and governance patterns for enterprise-scale GitHub deployments + +## Overview + +Repository governance establishes the policies, standards, and controls that ensure consistency, security, and compliance across your organization's codebase. As organizations scale from dozens to thousands of repositories, governance shifts from manual configuration to automated policy enforcement using repository templates, rulesets, and organization-wide settings. + +This guide covers enterprise governance patterns, the evolution from branch protection rules to repository rulesets, and strategies for managing repository lifecycles at scale. + +## Repository Visibility Models + +GitHub Enterprise Cloud provides three visibility levels that balance collaboration needs with security requirements: + +### Public Repositories + +**Characteristics:** +- Visible to all GitHub users +- Searchable via GitHub and search engines +- Can accept contributions from external users +- Free unlimited storage and bandwidth + +**Use Cases:** +- Open source projects +- Public documentation and marketing sites +- Community-driven tools and libraries +- Public APIs and SDKs + +**Security Considerations:** +- No sensitive data, credentials, or proprietary code +- Secret scanning automatically enabled +- Dependency security alerts active by default +- Consider the implications of public issue/PR discussions + +### Private Repositories + +**Characteristics:** +- Visible only to explicitly granted users +- Not searchable or discoverable externally +- Full access control via teams and collaborators +- Counted against enterprise seat licenses + +**Use Cases:** +- Proprietary application code +- Customer-specific implementations +- Internal tools and automation +- Work-in-progress features before public release + +**Access Patterns:** +- Grant access via teams (recommended) rather than individuals +- Use read/triage/write/maintain/admin role hierarchy +- Audit access regularly using organization insights +- Implement just-in-time access for contractors + +### Internal Repositories + +**Characteristics:** +- Available only in GitHub Enterprise Cloud/Server +- Visible to all enterprise members automatically +- Invisible to external collaborators +- Enables innersource collaboration patterns + +**Use Cases:** +- Shared libraries and frameworks +- Platform services and APIs +- DevOps tooling and infrastructure code +- Enterprise design systems and component libraries + +**Innersource Benefits:** +- Reduces duplication across teams +- Increases code reuse and standardization +- Enables cross-team collaboration without explicit access grants +- Maintains security boundaries for external parties + +```mermaid +graph TB + subgraph "Visibility Decision Tree" + A[New Repository] --> B{Contains Sensitive Data?} + B -->|Yes| C[Private] + B -->|No| D{Enterprise-Wide Access?} + D -->|Yes| E[Internal] + D -->|No| F{Public Community Value?} + F -->|Yes| G[Public] + F -->|No| C + end + + style C fill:#ff6b6b + style E fill:#ffd93d + style G fill:#6bcf7f +``` + +## Repository Templates and Standardization + +Repository templates enable consistent initialization of new repositories with pre-configured files, structure, and settings. This reduces onboarding friction and ensures compliance from day one. + +### Template Components + +**Essential Files:** +- `README.md` with project structure guidelines +- `.gitignore` for language/framework-specific exclusions +- `LICENSE` file with approved organization license +- `CODEOWNERS` with default ownership rules +- `.github/workflows/` with CI/CD starter templates +- `SECURITY.md` with vulnerability reporting procedures +- `CONTRIBUTING.md` with contribution guidelines +- Dependency manifests with approved baseline packages + +**GitHub-Specific Configurations:** +- Issue templates (`.github/ISSUE_TEMPLATE/`) +- Pull request templates (`.github/pull_request_template.md`) +- Funding configuration (`.github/FUNDING.yml`) +- Dependabot configuration (`.github/dependabot.yml`) +- Security policy (`.github/SECURITY.md`) + +### Template Strategy Patterns + +**1. Monolithic Template:** +- Single template with all possible configurations +- Teams remove unnecessary components +- **Pros:** Comprehensive, nothing forgotten +- **Cons:** Overhead, teams may skip cleanup + +**2. Tech Stack Templates:** +- Separate templates per language/framework +- `python-service-template`, `react-app-template`, `go-microservice-template` +- **Pros:** Focused, immediately useful +- **Cons:** More templates to maintain + +**3. Tiered Templates:** +- Basic template with minimal structure +- Enhanced templates with additional tooling +- Enterprise template with full compliance +- **Pros:** Flexibility for different project types +- **Cons:** Teams may choose wrong tier + +**Best Practice:** Combine approaches with base template + tech-specific additions + +### Implementing Template Governance + +```bash +# Create a repository template via API +gh api \ + --method PATCH \ + /repos/ORGANIZATION/repo-template \ + -f is_template=true + +# Generate new repository from template +gh repo create my-org/new-project \ + --template my-org/repo-template \ + --private \ + --clone + +# Audit repositories created from templates +gh api \ + --paginate \ + 'orgs/ORGANIZATION/repos?per_page=100' \ + --jq '.[] | select(.template_repository != null) | {name, template: .template_repository.full_name}' +``` + +**Template Maintenance:** +- Review and update quarterly +- Track template adoption rates +- Survey teams for pain points +- Version templates for major changes +- Document template changelog + +## Branch Protection Rules vs Repository Rulesets + +GitHub provides two mechanisms for enforcing repository policies: legacy **Branch Protection Rules** and modern **Repository Rulesets**. Understanding when to use each is critical for scalable governance. + +### Branch Protection Rules (Legacy) + +**Characteristics:** +- Configured per repository +- Applied to branch name patterns (`main`, `release/*`) +- Limited scope and inheritance +- No organization-wide enforcement +- Separate configuration for each repository + +**Limitations:** +- No organizational defaults +- Manual configuration at scale requires automation +- Cannot target tags +- Limited bypass mechanisms +- No import/export capability +- Difficult to audit compliance across repos + +**When to Use:** +- Single repository or small organizations +- Temporary one-off policies +- Backward compatibility requirements +- Simple linear branch workflows + +### Repository Rulesets (Modern Approach) + +**Characteristics:** +- Organization or repository scope +- JSON-exportable and importable +- Target branches, tags, or both +- Enforcement and evaluation modes +- Granular bypass permissions +- API-first design for automation + +**Key Advantages:** + +1. **Organization-Wide Enforcement:** + - Define once, apply to all repositories + - Automatic application to new repositories + - Consistent policy across enterprise + +2. **Bypass Actors with Conditions:** + - Grant exceptions to specific users, teams, or apps + - Require manual approval for bypass + - Audit all bypass events + - Time-based exceptions (via custom apps) + +3. **Advanced Targeting:** + - Include/exclude patterns: `main`, `develop`, `release/**`, `~hotfix/*` + - Target by repository properties (visibility, template origin) + - Default branch vs all branches + - Tag protection with version patterns (`v*`, `v[0-9].[0-9].[0-9]`) + +4. **Portability:** + - Export ruleset as JSON + - Version control ruleset definitions + - Import across organizations + - Disaster recovery and compliance as code + +5. **Evaluation Mode:** + - Test policies without enforcement + - Gather compliance metrics before blocking + - Gradual rollout with real data + +```mermaid +graph LR + subgraph "Branch Protection Rules" + BP1[Repository A] --> BP2[Manual Config] + BP3[Repository B] --> BP4[Manual Config] + BP5[Repository C] --> BP6[Manual Config] + end + + subgraph "Repository Rulesets" + RS1[Organization Ruleset] --> RS2[Auto Applied] + RS2 --> RS3[Repository A] + RS2 --> RS4[Repository B] + RS2 --> RS5[Repository C] + RS2 --> RS6[Future Repos] + end + + style RS1 fill:#6bcf7f + style BP2 fill:#ff6b6b + style BP4 fill:#ff6b6b + style BP6 fill:#ff6b6b +``` + +### Migration Path: Branch Protection to Rulesets + +**Phase 1: Assessment** +```bash +# Audit existing branch protection rules +gh api --paginate '/orgs/ORGANIZATION/repos' \ + --jq '.[] | .full_name' | \ + xargs -I {} gh api '/repos/{}/branches/main/protection' 2>/dev/null + +# Identify common patterns +# - Required status checks +# - Required reviews +# - Signed commits +# - Linear history requirements +``` + +**Phase 2: Pilot Ruleset** +1. Create organization ruleset in **Evaluate** mode +2. Monitor compliance via ruleset insights +3. Identify repositories that would fail +4. Address policy violations or adjust ruleset + +**Phase 3: Enforcement** +1. Switch ruleset to **Active** mode +2. Communicate changes to development teams +3. Document bypass procedures +4. Disable redundant branch protection rules + +**Phase 4: Optimization** +1. Refine targeting based on repository attributes +2. Create specialized rulesets for different project types +3. Automate ruleset updates via API +4. Regular compliance audits + +## Repository Ruleset Deep Dive + +### Ruleset Structure and Targeting + +**Ruleset Components:** + +```json +{ + "name": "Production Protection", + "target": "branch", + "enforcement": "active", + "bypass_actors": [ + { + "actor_id": 1, + "actor_type": "Team", + "bypass_mode": "always" + } + ], + "conditions": { + "ref_name": { + "include": ["refs/heads/main", "refs/heads/production"], + "exclude": ["refs/heads/sandbox/*"] + } + }, + "rules": [ + { + "type": "pull_request", + "parameters": { + "required_approving_review_count": 2, + "dismiss_stale_reviews_on_push": true, + "require_code_owner_review": true, + "require_last_push_approval": true + } + }, + { + "type": "required_status_checks", + "parameters": { + "required_status_checks": [ + { + "context": "ci/build", + "integration_id": 12345 + }, + { + "context": "security/scan" + } + ], + "strict_required_status_checks_policy": true + } + }, + { + "type": "commit_author_email_pattern", + "parameters": { + "operator": "ends_with", + "pattern": "@company.com" + } + } + ] +} +``` + +### Required Status Checks + +Status checks integrate CI/CD systems with merge requirements, ensuring all automated validations pass before code merges. + +**Configuration Best Practices:** + +1. **Specific Context Names:** + - Use structured naming: `ci/build`, `security/sast`, `test/unit` + - Avoid generic names like `build` or `test` + - Include tool identifiers: `sonarqube/quality-gate` + +2. **Strict Status Checks:** + - Enable "Require branches to be up to date" for `main` + - Prevents merge races and integration conflicts + - Increases merge queue wait times (consider merge strategies) + +3. **Integration ID Binding:** + - Lock status checks to specific GitHub App installations + - Prevents impersonation from similarly-named checks + - Critical for security-sensitive validations + +4. **Exemptions and Bypass:** + - Allow bot accounts to bypass for automated releases + - Require manual approval for emergency hotfixes + - Grant security teams bypass for critical patches + +**Common Pitfalls:** +- **Fragile checks:** Status check name changes break policy +- **Overly strict:** Requiring all checks blocks legitimate work +- **Missing checks:** New workflows not added to requirements +- **Circular dependencies:** Status check waits for merge to run + +### Required Reviews and CODEOWNERS + +Code review requirements enforce quality gates and knowledge distribution across teams. + +**Review Configuration:** + +```yaml +# Required approving review count: 1, 2, or more +# Considerations: +# - 1 review: Fast, minimal bottleneck, less scrutiny +# - 2 reviews: Balanced, reduces single-point-of-failure +# - 3+ reviews: High-security contexts, slows velocity + +# Dismiss stale reviews on push +# - New commits invalidate previous approvals +# - Prevents approval-then-modify pattern +# - Increases back-and-forth but improves safety + +# Require review from Code Owners +# - CODEOWNERS file defines ownership +# - Automatic reviewer assignment +# - Can require all owners or any owner + +# Require approval of most recent reviewable push +# - Prevents last-second changes after approval +# - Most recent push must have review +# - Reduces "approve and modify" risk +``` + +**CODEOWNERS Integration:** + +``` +# Repository root CODEOWNERS +# Each line specifies file pattern and owners + +# Global owners (fallback) +* @org/engineering-leads + +# Service ownership +/services/auth/ @org/auth-team +/services/billing/ @org/billing-team + +# Frontend ownership +/frontend/ @org/frontend-team +*.tsx @org/frontend-team + +# Infrastructure as code +*.tf @org/devops +/.github/workflows/ @org/devops @org/security + +# Security-sensitive files (multiple owners required) +/config/secrets/ @org/security @org/engineering-leads +SECURITY.md @org/security + +# Documentation +/docs/ @org/technical-writers +*.md @org/technical-writers + +# Specific file overrides +/docs/security/ @org/security @org/technical-writers +``` + +**CODEOWNERS Advanced Patterns:** + +1. **Hierarchical Ownership:** + - More specific patterns override general ones + - Last matching pattern wins + - Use for escalating sensitivity levels + +2. **Shared Ownership:** + - Multiple teams/individuals on one pattern + - Any owner can approve (unless "require all") + - Reduces bottlenecks for cross-team code + +3. **Organizational Structure:** + - Mirror org chart in ownership + - Align with on-call rotations + - Consider timezone distribution + +4. **Ownership Validation:** + ```bash + # Test CODEOWNERS syntax + gh api \ + -X POST \ + /repos/OWNER/REPO/code-scanning/codeowners/errors + + # Identify files without owners + git ls-files | while read file; do + owner=$(gh api /repos/OWNER/REPO/contents/"$file" \ + --jq '.codeowners[0].login' 2>/dev/null) + [[ -z "$owner" ]] && echo "No owner: $file" + done + ``` + +### Signed Commits Requirement + +Commit signing cryptographically verifies author identity, preventing impersonation and ensuring commit integrity. + +**Signing Methods:** + +1. **GPG (GNU Privacy Guard):** + - Traditional method, widely supported + - Requires key management infrastructure + - Works with git command line + +2. **SSH Signing:** + - Uses SSH keys (simpler for users) + - Supported in Git 2.34+ + - Reuses existing SSH infrastructure + +3. **S/MIME:** + - Certificate-based signing + - Enterprise PKI integration + - Less common in GitHub workflows + +4. **GitHub Web Commits:** + - Automatically signed by GitHub + - No user action required + - Web UI edits, PR merges, squash commits + +**Enforcement Configuration:** + +```json +{ + "type": "required_signatures", + "parameters": {} +} +``` + +**Implementation Considerations:** + +- **Developer Experience:** + - GPG setup is complex for non-technical users + - SSH signing reduces friction significantly + - Provide clear documentation and tooling + +- **CI/CD Integration:** + - Bot accounts need signing keys + - GitHub Actions can use GITHUB_TOKEN for signed commits + - Automated releases must handle signing + +- **Key Rotation:** + - Plan for key expiration and renewal + - Historical commits remain valid with expired keys + - Document key revocation procedures + +- **Verification Enforcement:** + - Ruleset blocks unsigned commits + - Rebase operations may strip signatures + - Force-push restrictions complement signing + +**Bypass Scenarios:** +- Emergency hotfix procedures +- Historical repository imports +- Third-party integration commits +- Automated dependency updates (if bot unsigned) + +## Tag Protection Rules + +Tags mark releases and milestones; protecting them prevents accidental or malicious modification of release history. + +**Tag Protection Patterns:** + +``` +v* # All version tags +v[0-9].[0-9].* # Semantic versions only +release-* # Release candidates +stable/* # Stable release branches +prod-* # Production deployments +``` + +**Tag Ruleset Configuration:** + +```json +{ + "name": "Release Tag Protection", + "target": "tag", + "enforcement": "active", + "conditions": { + "ref_name": { + "include": ["refs/tags/v*", "refs/tags/release-*"] + } + }, + "rules": [ + { + "type": "creation", + "parameters": { + "restricted": true + } + }, + { + "type": "update", + "parameters": { + "restricted": true + } + }, + { + "type": "deletion", + "parameters": { + "restricted": true + } + } + ], + "bypass_actors": [ + { + "actor_id": 123, + "actor_type": "Team", + "bypass_mode": "always" + } + ] +} +``` + +**Tag Management Governance:** + +1. **Creation Restrictions:** + - Only release managers can create version tags + - Automated release workflows via GitHub Actions + - Pre-tag validation (changelog, tests pass) + +2. **Immutability:** + - Block tag updates after creation + - Prevents "tag reuse" that confuses dependency managers + - Forces new version for corrections + +3. **Deletion Prevention:** + - Tags represent historical releases + - Deletion breaks reproducibility + - If deletion necessary, requires escalated approval + +4. **Signing Integration:** + - Require signed tags for releases + - Cryptographic proof of release approval + - Compatible with GPG/SSH signing + +**Anti-Patterns:** +- Reusing tag names (`v1.0` deleted and recreated) +- Unprotected pre-release tags (`alpha-*`, `beta-*`) +- Tag/branch naming conflicts +- Manual tag creation without CI validation + +## Push Rulesets and File Path Restrictions + +Push rulesets extend governance to file-level granularity, enabling controls based on file paths and content patterns. + +**File Path Restriction Use Cases:** + +1. **Infrastructure Protection:** + - Block direct changes to `.github/workflows/` (require PR) + - Protect Terraform state files from accidental commits + - Restrict Kubernetes manifests to DevOps team + +2. **Security Boundaries:** + - Prevent credential files (`*.key`, `*.pem`) + - Block sensitive config paths (`/config/production/`) + - Restrict security policy modifications + +3. **Architecture Governance:** + - Enforce module boundaries in monorepos + - Prevent cross-team dependencies + - Require architectural review for shared library changes + +4. **Compliance Requirements:** + - Immutable audit logs (`/audit/*`) + - Protected compliance documentation + - Regulated data schema files + +**File Path Ruleset Configuration:** + +```json +{ + "name": "Infrastructure File Protection", + "target": "push", + "enforcement": "active", + "rules": [ + { + "type": "file_path_restriction", + "parameters": { + "restricted_file_paths": [ + ".github/workflows/*.yml", + "terraform/*.tfstate", + "config/production/*", + "**/*.key", + "**/*.pem" + ] + } + }, + { + "type": "file_extension_restriction", + "parameters": { + "restricted_file_extensions": [ + ".exe", + ".dll", + ".so", + ".dylib" + ] + } + } + ] +} +``` + +**Commit Metadata Rules:** + +```json +{ + "rules": [ + { + "type": "commit_message_pattern", + "parameters": { + "operator": "starts_with", + "pattern": "^(feat|fix|docs|chore|refactor|test):" + } + }, + { + "type": "commit_author_email_pattern", + "parameters": { + "operator": "ends_with", + "pattern": "@company.com" + } + }, + { + "type": "committer_email_pattern", + "parameters": { + "operator": "ends_with", + "pattern": "@company.com" + } + } + ] +} +``` + +**Advanced Push Rules:** + +- **Maximum file size:** Block large binary commits +- **Maximum file path length:** Prevent Windows compatibility issues +- **Branch name patterns:** Enforce naming conventions +- **Non-fast-forward prevention:** Block force pushes + +**Implementation Strategy:** + +1. **Start with Evaluate Mode:** + - Monitor violations without blocking + - Identify legitimate vs problematic patterns + - Adjust rules based on real usage + +2. **Gradual Rollout:** + - Apply to new repositories first + - Test with pilot teams + - Full enforcement after refinement + +3. **Clear Communication:** + - Document allowed and blocked patterns + - Provide workaround procedures + - Offer bypass request process + +4. **Automated Remediation:** + - Pre-commit hooks for local validation + - CI checks that duplicate restrictions + - Helpful error messages with solutions + +## Merge Strategies and Settings + +Merge strategies determine how pull requests integrate into target branches, affecting git history, bisectability, and workflow patterns. + +### Merge Method Comparison + +| Method | History | Bisectable | Use Case | +|--------|---------|------------|----------| +| **Merge Commit** | Full PR history preserved | Yes, each commit | Long-lived feature branches, detailed history needed | +| **Squash and Merge** | Single commit per PR | Yes, by PR | Clean history, work-in-progress commits, GitHub Flow | +| **Rebase and Merge** | Linear history, all commits | Yes, each commit | Linear history preference, polished commits required | + +**Merge Commit:** +``` +main: A---B-------E---F + \ / +feature: C---D +``` +- Preserves all feature branch commits +- Creates merge commit (E) with two parents +- Easy to identify when feature merged +- Can clutter history with "wip" commits + +**Squash and Merge:** +``` +main: A---B---C' + +feature: C₁---C₂---C₃ (not in main history) +``` +- Combines all feature commits into single commit (C') +- PR description becomes commit message +- Clean linear history +- Loses granular commit history + +**Rebase and Merge:** +``` +main: A---B---C---D +``` +- Replays feature commits on top of base +- No merge commit created +- Linear history maintained +- Requires clean, meaningful commits + +### Merge Queue + +Merge queue serializes pull request merges to prevent integration failures when multiple PRs pass checks but conflict when combined. + +**Problem Without Merge Queue:** +1. PR #1 passes checks against `main` at commit A +2. PR #2 passes checks against `main` at commit A +3. PR #1 merges to `main` (now at commit B) +4. PR #2 merges to `main` (now at commit C) +5. **Result:** Commit C may break despite both PRs passing individually + +**Merge Queue Solution:** + +```mermaid +sequenceDiagram + participant PR1 as PR #1 + participant PR2 as PR #2 + participant Queue as Merge Queue + participant Main as main branch + + PR1->>Queue: Ready to merge (checks passed) + Queue->>Queue: Create merge group (main + PR1) + Queue->>Queue: Run required checks on merge group + + PR2->>Queue: Ready to merge (checks passed) + Queue->>Queue: Queue PR2 (waits for PR1) + + Queue-->>Main: PR1 checks pass + Queue->>Main: Merge PR1 + + Queue->>Queue: Create merge group (main + PR2) + Queue->>Queue: Run required checks on merge group + Queue-->>Main: PR2 checks pass + Queue->>Main: Merge PR2 +``` + +**Merge Queue Configuration:** + +```yaml +# .github/merge_queue.yml +merge_method: squash +min_queue_size: 2 +max_queue_size: 10 +merge_group_batch_size: 5 +ci_status_timeout: 60 +``` + +**Parameters:** + +- **Merge Method:** Enforces consistent merge strategy +- **Minimum Queue Size:** Wait for N PRs before creating groups (batching) +- **Maximum Queue Size:** Limit concurrent testing +- **Batch Size:** Test multiple PRs together (faster but risk of failure) +- **CI Timeout:** Cancel stalled checks + +**When to Enable:** +- High-frequency merges (multiple per hour) +- Strict status checks with long CI runs +- Flaky tests that occasionally fail +- Cross-PR dependencies and conflicts + +**Bypass Patterns:** +- Emergency hotfixes (with appropriate approvals) +- Documentation-only changes +- Automated dependency updates (grouped separately) + +### Repository Merge Settings + +**Auto-Merge:** +- PR author enables auto-merge +- Automatically merges when checks pass and approvals met +- Reduces manual monitoring and click-through + +**Automatic Branch Deletion:** +- Deletes head branch after PR merge +- Reduces branch clutter +- Preserves branch in PR for audit trail + +**Allow/Disallow Merge Types:** +- Organization or repository level +- Restrict to single method for consistency +- Or allow flexibility based on PR content + +**Suggestions:** +- **GitHub Flow (single long-lived branch):** Squash-only +- **Git Flow (feature/release branches):** Merge commit or rebase +- **Trunk-Based Development:** Squash or rebase +- **Monorepos with team boundaries:** Merge commit for traceability + +## Repository Lifecycle Management + +```mermaid +stateDiagram-v2 + [*] --> Template: Create from template + [*] --> Import: Import existing + [*] --> Empty: Initialize empty + + Template --> Active + Import --> Active + Empty --> Active + + Active --> Active: Development + Active --> Archived: End of life + Active --> Transferred: Change ownership + Active --> Private: Reduce visibility + Active --> Internal: Share internally + Active --> Public: Open source + + Archived --> Active: Unarchive (rare) + Transferred --> Active: Continue in new org + + Private --> Internal: Increase visibility + Private --> Public: Open source release + Internal --> Private: Restrict access + Internal --> Public: Open source release + Public --> Private: Never (best practice) + + Archived --> [*]: Deletion (after retention) +``` + +### Repository States + +**Active:** +- Normal development state +- All features enabled (issues, PRs, Actions) +- Team members can push/merge +- Full automation and integrations + +**Archived:** +- Read-only state +- No new issues, PRs, or commits +- Existing content remains accessible +- Reduces clutter in repository lists +- Can be unarchived if needed + +**Transferred:** +- Ownership moved to different org/user +- Preserves full history and metadata +- Redirects from old URL (temporarily) +- Access control reset to destination org + +**Deleted:** +- Permanent removal (after 90-day recovery period) +- All data destroyed after recovery window +- Forks remain unaffected +- Should be rare, prefer archival + +### Archival Policies + +**When to Archive:** + +1. **Project Completion:** + - One-time deliverables finished + - Documentation/research projects concluded + - Pilot/POC no longer maintained + +2. **Superseded by Successor:** + - Code migrated to new repository + - Rewrite or major refactor in new location + - Archive old, link to new in README + +3. **Abandoned/Deprecated:** + - No development for extended period (6-12 months) + - Technology stack obsolete + - Business need eliminated + +4. **Compliance Requirements:** + - Regulatory retention periods met + - Data must be preserved but not modified + - Audit trail preservation + +**Archival Process:** + +```bash +# Pre-archival checklist +# 1. Update README with archive notice +echo "# ⚠️ ARCHIVED\n\nThis repository is archived and no longer maintained.\n\n**Reason:** Project completed\n**Date:** $(date +%Y-%m-%d)\n**Successor:** https://github.com/org/new-repo\n\n$(cat README.md)" > README.md + +# 2. Create final release/tag +git tag -a "archive-$(date +%Y%m%d)" -m "Archived on $(date +%Y-%m-%d)" +git push origin "archive-$(date +%Y%m%d)" + +# 3. Archive repository +gh repo archive OWNER/REPO --yes + +# 4. Update organization documentation +# Add to "Archived Projects" list +``` + +**Post-Archival:** +- Issues and PRs remain readable +- README should explain archive status +- Link to successor or migration docs +- Security alerts disabled (no patches needed) + +**Unarchive Scenarios:** +- Critical bug discovery requiring fix +- Dependency revival by community +- Historical research requiring modification +- Mistaken archival + +### Transfer Policies + +Repository transfers change ownership between users or organizations, requiring careful planning to maintain continuity. + +**Transfer Scenarios:** + +1. **Organizational Restructuring:** + - Team split into separate org + - Acquisition/merger consolidation + - Open source → enterprise fork + +2. **Visibility Changes:** + - Personal project → organization + - Incubation project → official product + - Experimental → production + +3. **Vendor/Customer Handoff:** + - Consultant deliverable transfer + - Customer-specific implementation + - Outsourced development completion + +**Transfer Implications:** + +| Aspect | Impact | Mitigation | +|--------|--------|------------| +| **URLs** | Redirect created temporarily | Update CI/CD and docs | +| **Access** | Reset to destination org teams | Pre-configure teams | +| **Secrets** | Not transferred | Document and recreate | +| **Actions** | Workflow runs lost | Archive artifacts first | +| **Apps** | Webhooks may break | Update app configurations | +| **Forks** | Remain at original location | Fork relationships preserved | + +**Transfer Process:** + +```bash +# 1. Audit dependencies +gh repo view OWNER/REPO --json url,sshUrl +grep -r "github.com/OWNER/REPO" . + +# 2. Document integrations +gh api /repos/OWNER/REPO/hooks +gh api /repos/OWNER/REPO/keys + +# 3. Export issues/PRs if needed +gh issue list --repo OWNER/REPO --json number,title,state --limit 1000 > issues.json + +# 4. Perform transfer +gh repo transfer OWNER/REPO NEW_OWNER + +# 5. Update references +find . -type f -exec sed -i 's/OWNER\/REPO/NEW_OWNER\/REPO/g' {} + +``` + +**Post-Transfer Checklist:** +- Verify webhook configurations +- Re-add deploy keys and secrets +- Test CI/CD pipelines +- Update documentation links +- Notify stakeholders and teams +- Monitor for broken integrations + +## Innersource Patterns with Internal Repositories + +Innersource applies open source collaboration patterns within organizational boundaries, leveraging internal repositories to balance openness with security. + +### Innersource Benefits + +**Code Reuse:** +- Discover existing solutions before building new +- Reduce duplication across teams +- Share libraries and frameworks enterprise-wide + +**Knowledge Distribution:** +- Learn from other teams' approaches +- Cross-pollinate ideas and patterns +- Break down organizational silos + +**Quality Improvement:** +- Broader review audience +- More eyes on security and performance +- Community-driven improvements + +**Talent Development:** +- Exposure to different codebases +- Mentorship opportunities across teams +- Career mobility within organization + +### Innersource Governance Models + +**1. Open Contribution Model:** +- All employees can read and contribute +- Automated approval for minor changes +- Core team review for major changes +- Fast iteration, broad engagement + +**2. Gatekeeper Model:** +- All employees can read +- Contributions require proposal/RFC +- Core team controls acceptance +- Higher quality bar, slower pace + +**3. Federated Model:** +- Multiple teams co-maintain +- Rotating responsibilities +- Shared on-call for support +- Distributed ownership + +**4. Platform Model:** +- Centralized platform team maintains +- Other teams consume as dependencies +- Contributions accepted but not required +- Clear support and SLA expectations + +### Setting Up Innersource Repositories + +**Repository Configuration:** + +```yaml +# .github/INNERSOURCE.md +# Innersource Project: Cloud SDK + +## Vision +Provide a unified SDK for internal cloud services. + +## Maintainers +- @platform-team (primary) +- @devex-team (secondary) + +## Contributing +1. Check existing issues/PRs for duplicates +2. Open an issue to discuss before significant work +3. Follow coding standards in CONTRIBUTING.md +4. Ensure tests pass and coverage maintained +5. Request review from CODEOWNERS + +## Support +- Slack: #cloud-sdk-help +- Office hours: Tuesdays 2-3pm +- SLA: 48-hour response on issues + +## Usage Statistics +- 47 internal repositories depend on this SDK +- 230 active contributors across 12 teams +- 98% test coverage +``` + +**Discovery Mechanisms:** + +1. **Topics and Tags:** + - `innersource`, `platform`, `library`, `framework` + - Tech stack tags: `typescript`, `python`, `kubernetes` + - Team ownership: `team-platform`, `team-devex` + +2. **Organization README:** + - Curated list of innersource projects + - Getting started guides + - Contribution paths for beginners + +3. **GitHub Search:** + ```bash + # Find internal libraries + gh search repos --visibility internal --topic library --sort stars + + # Find projects by tech stack + gh search repos --visibility internal --language typescript --sort updated + ``` + +4. **Dependency Graphs:** + - Automatic discovery via `package.json`, `go.mod`, `pom.xml` + - GitHub's dependency graph shows usage + - Renovate/Dependabot highlight internal dependencies + +**Innersource Metrics:** + +```bash +# Contribution diversity +gh api /repos/ORG/REPO/stats/contributors \ + | jq 'group_by(.author.login) | length' + +# Issue response time +gh issue list --repo ORG/REPO --json createdAt,closedAt --limit 100 \ + | jq '[.[] | select(.closedAt != null) | + ((.closedAt | fromdateiso8601) - (.createdAt | fromdateiso8601)) / 86400] + | add / length' + +# Cross-team participation +gh pr list --repo ORG/REPO --json author --limit 200 \ + | jq '[.[].author.login] | unique | length' +``` + +### Innersource Challenges and Solutions + +**Challenge: Undiscoverability** +- **Solution:** Mandatory topics, organization README, monthly showcases + +**Challenge: Unclear Ownership** +- **Solution:** CODEOWNERS, INNERSOURCE.md with SLAs, escalation paths + +**Challenge: Contribution Friction** +- **Solution:** Beginner-friendly issues, pair programming sessions, templates + +**Challenge: Quality Control** +- **Solution:** Rulesets enforce standards, automated testing, code review guidelines + +**Challenge: Sustainability** +- **Solution:** Dedicated maintainer time, rotation schedules, executive sponsorship + +**Challenge: Competing Priorities** +- **Solution:** Product/platform balance in team OKRs, contribution credit in performance reviews + +## Governance at Scale + +### Organization-Wide Patterns + +**Repository Naming Conventions:** +``` +-- + platform-auth-service + mobile-ios-app + data-analytics-pipeline + +- + checkout-api + checkout-frontend + checkout-workers +``` + +**Benefits:** +- Alphabetical grouping by team +- Clear ownership and purpose +- Search and filter efficiency + +**Default Settings Management:** + +```bash +# Set organization defaults via API +gh api \ + --method PATCH \ + /orgs/ORGANIZATION \ + -f default_repository_permission='read' \ + -f members_can_create_repositories=false \ + -f members_can_create_public_repositories=false + +# Apply settings to all repositories +gh repo list ORGANIZATION --limit 1000 --json name -q '.[].name' | \ +while read repo; do + gh api --method PATCH "/repos/ORGANIZATION/$repo" \ + -f has_issues=true \ + -f has_projects=false \ + -f has_wiki=false \ + -f delete_branch_on_merge=true \ + -f allow_squash_merge=true \ + -f allow_merge_commit=false \ + -f allow_rebase_merge=false +done +``` + +**Ruleset Hierarchy:** + +``` +Organization Level: + ├─ Critical Security (all repos) + │ ├─ Signed commits required + │ ├─ No secrets in commits + │ └─ Dependabot enabled + │ + ├─ Production Standards (production repos) + │ ├─ Required reviews: 2 + │ ├─ Required status checks + │ └─ No force push + │ + └─ Experimental (sandboxes) + └─ Relaxed rules + +Repository Level (additive): + └─ Project-Specific + ├─ Additional status checks + ├─ Project CODEOWNERS + └─ Custom file restrictions +``` + +### Compliance and Auditing + +**Audit Trails:** + +```bash +# Recent repository changes +gh api /orgs/ORGANIZATION/audit-log \ + --paginate \ + -f phrase='action:repo.*' \ + -f per_page=100 + +# Ruleset compliance violations +gh api /orgs/ORGANIZATION/rulesets/insights \ + --jq '.violations[] | {repo: .repository.name, rule: .rule_type, user: .actor.login}' + +# Access reviews +gh api /orgs/ORGANIZATION/outside_collaborators --paginate \ + | jq '.[] | {login, permissions}' + +# Branch protection audit +gh repo list ORGANIZATION --json nameWithOwner --limit 1000 \ + | jq -r '.[].nameWithOwner' \ + | xargs -I {} gh api /repos/{}/branches/main/protection 2>/dev/null +``` + +**Compliance Reporting:** + +| Control | Requirement | Validation | +|---------|-------------|------------| +| **Access Control** | Minimum 2FA for org members | `gh api /orgs/ORG/members?filter=2fa_disabled` | +| **Code Review** | All changes reviewed | Ruleset enforcement + audit log | +| **Vulnerability Mgmt** | Dependabot enabled | `gh api /repos/ORG/REPO/vulnerability-alerts` | +| **Secrets Detection** | Secret scanning enabled | Org security settings + alerts | +| **Least Privilege** | Teams used vs individuals | Permission audit script | +| **Data Retention** | Archived repos per policy | Repo age + last update query | + +**Automated Compliance:** + +```yaml +# .github/workflows/compliance-audit.yml +name: Compliance Audit +on: + schedule: + - cron: '0 2 * * 1' # Weekly Monday 2am + workflow_dispatch: + +jobs: + audit: + runs-on: ubuntu-latest + steps: + - name: Check 2FA Enforcement + run: | + DISABLED=$(gh api /orgs/${{ github.repository_owner }}/members?filter=2fa_disabled | jq length) + if [ "$DISABLED" -gt 0 ]; then + echo "::error::$DISABLED members without 2FA" + exit 1 + fi + + - name: Verify Dependabot + run: | + gh repo list ${{ github.repository_owner }} --limit 1000 --json name | \ + jq -r '.[].name' | \ + while read repo; do + enabled=$(gh api /repos/${{ github.repository_owner }}/$repo/vulnerability-alerts 2>&1) + if [[ $enabled == *"Not Found"* ]]; then + echo "::warning::Dependabot disabled on $repo" + fi + done + + - name: Audit Ruleset Coverage + run: | + # Get all rulesets + rulesets=$(gh api /orgs/${{ github.repository_owner }}/rulesets --jq '.[] | .id') + + # Verify critical rulesets exist + echo "$rulesets" | grep -q "Production Protection" || \ + echo "::error::Missing Production Protection ruleset" +``` + +### Migration and Change Management + +**Phased Rollout Strategy:** + +1. **Pilot Phase (Week 1-2):** + - Select 3-5 representative teams + - Apply rulesets in Evaluate mode + - Gather feedback and metrics + +2. **Refinement Phase (Week 3-4):** + - Adjust rules based on violations + - Document bypass procedures + - Create FAQ and troubleshooting guide + +3. **Gradual Rollout (Week 5-8):** + - Enable for 25% of repositories + - Monitor incident rate and support requests + - Expand to 50%, then 75% + +4. **Full Enforcement (Week 9+):** + - All repositories covered + - Automated compliance checking + - Regular review and adjustment + +**Communication Plan:** + +- **T-30 days:** Announce upcoming changes, rationale, timeline +- **T-14 days:** Technical deep-dive sessions for engineers +- **T-7 days:** Office hours for questions, bypass request process +- **T-1 day:** Final reminder, support channels highlighted +- **T-day:** Enable in Evaluate mode, monitor closely +- **T+7 days:** Switch to Active enforcement +- **T+30 days:** Retrospective, refine approach + +**Rollback Procedures:** + +```bash +# Disable ruleset temporarily +gh api \ + --method PATCH \ + /orgs/ORGANIZATION/rulesets/RULESET_ID \ + -f enforcement='disabled' + +# Export current config before changes +gh api /orgs/ORGANIZATION/rulesets/RULESET_ID > ruleset-backup.json + +# Restore previous version +gh api \ + --method PUT \ + /orgs/ORGANIZATION/rulesets/RULESET_ID \ + --input ruleset-backup.json +``` + +## Best Practices Summary + +### Repository Governance + +✅ **Do:** +- Use internal visibility for enterprise-wide sharing +- Create technology-specific repository templates +- Implement organization-level rulesets for consistency +- Require code review from CODEOWNERS +- Enable merge queue for high-traffic repositories +- Archive completed/deprecated projects +- Document bypass procedures clearly +- Monitor compliance via audit logs + +❌ **Don't:** +- Use public visibility for sensitive code +- Manually configure each repository individually +- Grant repository admin access broadly +- Allow force pushes to protected branches +- Let archived repositories accumulate unchecked +- Delete repositories (archive instead) +- Create overly restrictive rules without escape hatches +- Ignore ruleset violations in Evaluate mode + +### Ruleset Configuration + +✅ **Do:** +- Start with Evaluate mode before enforcement +- Use specific status check context names +- Bind checks to specific integration IDs +- Configure bypass actors for emergency access +- Export and version control ruleset JSON +- Document each rule's purpose and rationale +- Test rulesets on pilot repositories first + +❌ **Don't:** +- Skip the evaluation period +- Use generic check names like "build" or "test" +- Grant bypass access to large groups +- Modify rulesets without change control +- Enable all rules simultaneously +- Create rules without escape procedures +- Assume rulesets work identically across repos + +### Innersource Success + +✅ **Do:** +- Make internal repositories discoverable via topics +- Define clear ownership and SLAs +- Create beginner-friendly contribution paths +- Recognize contributions in performance reviews +- Provide dedicated maintainer time +- Host regular showcases and demos +- Measure contribution diversity + +❌ **Don't:** +- Assume discoverability without active promotion +- Leave ownership ambiguous +- Set high barriers to first contribution +- Treat innersource as "extra" work +- Let repositories stagnate without maintenance +- Silo knowledge within single teams +- Focus only on commit counts + +## References + +### Official Documentation + +- [Repository Settings and Features](https://docs.github.com/en/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features) - Comprehensive guide to repository configuration options +- [Managing Branch Protection Rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule) - Legacy branch protection configuration +- [About Repository Rulesets](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) - Modern ruleset capabilities and advantages +- [Creating Rulesets for Repositories](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository) - Step-by-step ruleset configuration +- [Managing Code Review Settings](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-pull-request-reviews-before-merging) - Pull request review requirements +- [About Code Owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) - CODEOWNERS file syntax and behavior +- [Managing Merge Queue](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) - Merge queue configuration and usage +- [About Commit Signature Verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) - GPG and SSH commit signing +- [About Tag Protection Rules](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules) - Protecting release tags +- [Archiving Repositories](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) - Repository archival procedures +- [Transferring a Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository) - Ownership transfer process + +### Related Documentation + +- [01-policy-inheritance.md](./01-policy-inheritance.md) - Organization and enterprise-level policy inheritance affecting repository settings +- [03-teams-permissions.md](./03-teams-permissions.md) - Team-based access control and permission levels for repositories +- [08-security-compliance.md](./08-security-compliance.md) - Security settings, secret scanning, and compliance requirements + +### Additional Resources + +- [GitHub Blog: Repository Rulesets GA](https://github.blog/changelog/2023-07-24-github-repository-rules-now-generally-available/) - Announcement and feature overview +- [Innersource Commons](https://innersourcecommons.org/) - Patterns and best practices for innersource +- [Git Flow vs GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow) - Branching strategies and merge patterns +- [Semantic Versioning](https://semver.org/) - Version numbering for tag protection strategies diff --git a/docs/08-security-compliance.md b/docs/08-security-compliance.md new file mode 100644 index 0000000..b1b82a5 --- /dev/null +++ b/docs/08-security-compliance.md @@ -0,0 +1,1127 @@ +# Security and Compliance + +## Overview + +GitHub Enterprise Cloud provides enterprise-grade security capabilities and compliance controls that enable organizations to protect intellectual property, secure software supply chains, and meet regulatory requirements. The GitHub Advanced Security (GHAS) suite delivers integrated security features that operate natively within the development workflow, enabling security teams to shift left while maintaining developer velocity. + +Security in GitHub Enterprise Cloud operates across multiple layers: code-level security through static analysis and secret detection, supply chain security through dependency management, access security through identity controls, and operational security through audit logging and compliance monitoring. Each layer integrates with enterprise policy frameworks, enabling centralized governance while allowing organizational autonomy within defined boundaries. + +Modern compliance requirements demand not just security controls but also evidence collection, audit trails, and continuous monitoring capabilities. GitHub Enterprise Cloud addresses these requirements through comprehensive audit logging, SIEM integration, security advisories, and certifications aligned with industry standards including SOC 2, ISO 27001, FedRAMP, and GDPR. Understanding these capabilities and their enterprise-scale implementation patterns is essential for security architects and compliance officers. + +This document explores the technical architecture, configuration patterns, and operational practices for implementing security and compliance at enterprise scale. It covers GitHub Advanced Security features, vulnerability management workflows, compliance automation, and integration patterns with enterprise security infrastructure. + +## GitHub Advanced Security (GHAS) + +### Architecture and Components + +GitHub Advanced Security represents an integrated security platform built directly into the GitHub development workflow. Unlike bolt-on security tools that operate externally, GHAS features are embedded in the code review process, pull request workflows, and repository security tabs, creating a frictionless security experience that encourages adoption and remediation. + +GHAS consists of three primary security scanning capabilities: + +**Code Scanning** analyzes source code for security vulnerabilities, coding errors, and quality issues using semantic analysis engines. The primary engine, CodeQL, performs deep static analysis by treating code as queryable data, enabling complex security pattern detection that goes beyond simple pattern matching. + +**Secret Scanning** monitors repositories for accidentally committed credentials, API keys, tokens, and other sensitive data. It operates continuously, scanning historical commits, new pushes, and pull requests. Push protection extends this capability by preventing secrets from being committed in the first place. + +**Dependency Scanning** through Dependabot identifies vulnerable dependencies in project manifests and lockfiles across multiple ecosystems. It provides automated pull requests for dependency updates, security patches, and version upgrades, enabling proactive vulnerability management. + +These three pillars work together to provide comprehensive security coverage across the software development lifecycle, from initial commit through production deployment. + +### Licensing and Enablement + +GitHub Advanced Security is licensed per active committer at the enterprise level. An active committer is defined as any user who has made at least one commit to a GHAS-enabled repository in the previous 90 days. This consumption-based licensing model ensures organizations only pay for security coverage on actively developed codebases. + +Enablement follows the enterprise policy hierarchy: + +```mermaid +graph TD + A[Enterprise GHAS License] -->|Allocates Seats| B[Organization Enablement] + B -->|Enables Features| C[Repository Configuration] + + A -->|Policy: Enforced| D[All Orgs Must Use] + A -->|Policy: Allowed| E[Org Chooses Enable/Disable] + + D -->|Automatic| F[GHAS Active All Repos] + E -->|Manual| G[Per-Repo Enablement] + + F --> H[Code Scanning Active] + F --> I[Secret Scanning Active] + F --> J[Dependabot Active] + + G --> K[Selective Feature Enable] + K --> H + K --> I + K --> J + + style A fill:#e1f5ff + style F fill:#d4edda + style K fill:#fff3cd +``` + +Enterprise administrators can enforce GHAS enablement through enterprise policies, requiring organizations to enable features on all repositories, or allow organizations to selectively enable GHAS on specific repositories based on criticality, compliance requirements, or development maturity. + +### Security Configurations at Scale + +Implementing GHAS across enterprise organizations requires standardized security posture management while respecting organizational autonomy. This involves: + +**Baseline Security Policies**: Establish minimum security standards across all organizations through enterprise policies. These may include mandatory code scanning on critical repositories, mandatory secret scanning with push protection, and required dependency vulnerability reviews before merge. + +**Organization Inheritance Hierarchy**: As described in [Policy Inheritance Architecture](./06-policy-inheritance.md), security configurations flow from enterprise to organization to repository levels. GHAS enablement policies cascade through this hierarchy, with organizations inheriting enterprise mandates while adding organization-specific controls. + +**Tiered Implementation Levels**: Organizations should classify repositories into tiers (critical, important, standard) and apply proportionate security scanning configurations. Critical repositories might require all GHAS features with strict blocking policies, while standard repositories enable core scanning with advisory-only configurations. + +**Security Scanning Strategy**: Define scanning frequency (continuous on PR, scheduled full scans), retention policies (how long to keep historical results), and alert management rules. Different repositories may require different strategies based on risk profile and development velocity. + +**Compliance-Driven Configuration**: For regulated codebases (healthcare, financial services, government), security configurations must align with compliance frameworks. This includes enabling all scanning features, maintaining complete audit trails, and implementing alerting for compliance-critical vulnerabilities. + +## Code Scanning with CodeQL + +### Overview and Enablement + +Code scanning uses static analysis engines to identify security vulnerabilities, code quality issues, and compliance violations in source code. GitHub's primary engine, CodeQL, performs deep semantic analysis by converting source code into a queryable database, enabling detection of complex vulnerability patterns that would be impossible with simple regex-based scanning. + +CodeQL analysis operates through multiple phases: + +1. **Database Generation**: Source code is compiled or interpreted, and an abstract syntax tree (AST) is generated and stored as a relational database +2. **Query Execution**: Security queries written in CodeQL Query Language execute against this database, identifying vulnerability patterns +3. **Result Aggregation**: Findings are deduplicated, ranked by severity, and presented in the GitHub UI with remediation guidance + +### Default Setup vs Advanced Configuration + +**Default Setup** provides pre-configured CodeQL scanning with GitHub-maintained queries covering OWASP Top 10, CWE Top 25, and common security anti-patterns. Default setup automatically: + +- Detects the repository's primary language(s) +- Downloads pre-built CodeQL databases for compiled languages +- Executes GitHub-maintained query suites +- Reports findings as code scanning alerts in the Security tab +- Runs on pull requests and on a weekly schedule + +Default setup is ideal for: +- Standard applications with single or dual primary languages +- Teams new to GHAS adoption +- Projects with straightforward build configurations +- Rapid enablement across many repositories + +**Advanced Configuration** through workflow files (`codeql-analysis.yml` or similar) provides full control over the scanning process: + +```yaml +name: CodeQL Advanced Analysis + +on: + push: + branches: [main, develop] + pull_request: + branches: [main] + schedule: + - cron: '0 2 * * 0' + +jobs: + analyze: + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write + + strategy: + matrix: + language: [java, python, javascript] + include: + - language: java + build-mode: manual + - language: javascript + build-mode: none + + steps: + - uses: actions/checkout@v3 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v2 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + queries: security-and-quality + config-file: .github/codeql-config.yml + + - name: Build + if: matrix.build-mode == 'manual' + run: | + ./build-scripts/compile.sh + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 + with: + category: "/${{ matrix.language }}-analysis" +``` + +Advanced configuration enables: +- Multi-language scanning with language-specific build processes +- Custom CodeQL query suites combining GitHub, community, and proprietary queries +- Granular build mode control (autobuild, manual, none) +- Integration with build caching and artifact management +- Fine-grained control over query execution and result filtering + +### CodeQL Query Language + +CodeQL Query Language is a declarative language designed for code analysis. Queries treat code as data, enabling complex vulnerability pattern detection: + +```codeql +// Example: Detect potential SQL injection vulnerabilities +import java + +class SqlInjectionVulnerability extends DataFlow::Configuration { + SqlInjectionVulnerability() { this = "sql-injection" } + + override predicate isSource(DataFlow::Node source) { + source.asExpr() instanceof ParameterExpr or + source.asExpr() instanceof FieldAccess + } + + override predicate isSink(DataFlow::Node sink) { + exists(MethodCall m | + m.getMethod().hasName("executeQuery") or + m.getMethod().hasName("execute") | + sink.asExpr() = m.getArgument(0) + ) + } +} + +from SqlInjectionVulnerability config, DataFlow::PathNode source, DataFlow::PathNode sink +where config.hasFlowPath(source, sink) +select source.getNode(), source, sink, "Potential SQL injection from user input" +``` + +Key concepts: +- **Data Flow Analysis**: Tracks how data flows through programs, identifying when untrusted input reaches sensitive operations +- **Taint Analysis**: Marks user-controlled data as tainted, following it through transformations to detect vulnerabilities +- **Predicates**: Reusable logical definitions (sources, sinks, sanitizers) that define vulnerability patterns +- **Path Finding**: Explains the exact code path from vulnerability source to sink + +Organizations can create custom queries for: +- Industry-specific compliance violations (GDPR data handling, HIPAA encryption) +- Internal coding standards enforcement +- Architecture anti-pattern detection +- Framework-specific vulnerabilities + +### Severity Levels and Alert Management + +CodeQL findings are categorized by severity: + +| Severity | Definition | Response Time | Example | +|----------|-----------|---|---------| +| **Critical** | Immediate risk to security or data integrity | 1-4 hours | Remote Code Execution, Authentication Bypass, SQL Injection | +| **High** | Significant security exposure requiring urgent remediation | 1-2 days | Hardcoded credentials, Insecure deserialization, Path traversal | +| **Medium** | Important but not immediately exploitable vulnerabilities | 1-2 weeks | Information disclosure, Insecure cryptographic practices | +| **Low** | Coding anti-patterns with indirect security implications | 1-2 months | Use of deprecated APIs, Potential null pointer dereference | +| **Note** | Code quality and maintainability issues | No SLA | Code duplication, Complex logic patterns | + +Each security level has an associated Cost of Remediation Index (CRI): +- Critical: CRI = 1 (must fix before merge in critical repos) +- High: CRI = 0.8 (should fix before merge, exceptions allowed with risk acceptance) +- Medium: CRI = 0.5 (fix within sprint, not blocking) +- Low: CRI = 0.2 (accumulate and batch fix) + +### Build Mode and Multi-Language Analysis + +CodeQL analysis requires understanding the source code structure, which varies by language: + +**Interpreted Languages** (Python, JavaScript, TypeScript, Ruby): +- Source code directly analyzed without compilation +- Build mode: `none` or `autobuild` +- Faster analysis, no build artifacts required + +**Compiled Languages** (Java, C/C++, Go, C#): +- Source code must be compiled to generate AST +- Build mode: `autobuild` (GitHub attempts to detect build process) or `manual` (explicit build commands) +- Requires compilation success for accurate analysis + +**Database Caching** improves analysis performance: + +```yaml +- name: CodeQL Analysis with Caching + uses: github/codeql-action/analyze@v2 + with: + upload: always + category: "/${{ matrix.language }}" + ram: 4096 + threads: 4 +``` + +## Secret Scanning + +### Architecture and Detection Pipeline + +Secret scanning continuously monitors repositories for accidentally committed credentials, API keys, OAuth tokens, and other sensitive data. It operates at multiple points: + +1. **Push Protection**: Blocks pushes containing detected secrets before they reach the repository +2. **Historical Scanning**: Analyzes entire repository history when secret scanning is enabled +3. **Ongoing Monitoring**: Continuously scans new commits and pull requests +4. **Custom Pattern Detection**: Organizations define custom secret patterns matching internal credential formats + +### Supported Patterns + +GitHub secret scanning detects patterns for major cloud providers and services: + +**Cloud Infrastructure**: +- AWS Access Keys, AWS Secret Keys, AWS Session Tokens +- Azure Connection Strings, Azure Storage Account Keys +- Google API Keys, Google Cloud Service Account Keys +- GitHub Personal Access Tokens, GitHub OAuth Tokens, GitHub Refresh Tokens + +**SaaS Platforms**: +- Slack API Tokens, Slack Bot Tokens, Slack Webhook URLs +- Twilio API Keys, SendGrid API Keys +- Stripe API Keys, PayPal Credentials +- Datadog API Keys, New Relic License Keys + +**Version Control and CI/CD**: +- SSH Private Keys (OpenSSH, PuTTY, SecureShell formats) +- CI/CD Tokens (CircleCI, Travis CI, Jenkins) +- Container Registry Credentials (Docker Hub, Quay.io) +- NPM and Maven Repository Tokens + +**Enterprise Services**: +- Splunk Tokens, Kubernetes Tokens +- JFrog Artifactory Credentials +- Database Connection Strings + +Each detected pattern triggers an alert with: +- Location of the secret in repository history +- Type of credential detected +- Timestamp of commit containing the credential +- Remediation options (revoke, rotate, suppress) + +### Push Protection Configuration + +Push protection prevents secrets from being committed, enabling inline remediation before exposure: + +```mermaid +graph TD + A[Developer Pushes Code] --> B{Secret Scanning Enabled?} + B -->|No| C[Push Proceeds] + B -->|Yes| D{Secret Pattern Detected?} + + D -->|No Pattern| C + D -->|Pattern Found| E[Push Blocked] + + E --> F{Allow Push?} + F -->|Override| G[Secret Logged & Block Bypassed] + F -->|Remediate| H[Remove Secret from Code] + + G --> I[Alert to Security Team] + H --> J[Re-push Clean Code] + J --> C + + I --> K[Audit Log Entry] + K --> L[Incident Tracking] + + style E fill:#ff9999 + style H fill:#99ff99 + style I fill:#ffcc99 + style K fill:#99ccff +``` + +Configuration through organization settings: + +```yaml +# Enable Push Protection in organization +PUT /orgs/{org}/code_security_and_analysis/push_protection +{ + "enabled": true, + "threshold": "all_patterns", + "bypass_allowed": true, + "bypass_require_pr": true, + "bypass_log_to_audit": true +} +``` + +When a secret is detected during push: +1. Push is blocked at the server before reaching the repository +2. Developer receives local error message with secret type and location +3. Developer can choose to remove the secret or request override +4. Override requests are logged to audit trail with business justification +5. Security team receives alert for every override, enabling threat tracking + +### Custom Patterns and Enterprise Integration + +Organizations can define custom secret patterns for internal credential formats: + +```json +{ + "name": "Internal API Token Format", + "pattern": "api_token_[a-zA-Z0-9]{32}", + "secret_group": 0, + "test_values": [ + "api_token_abcdefghijklmnopqrstuvwxyz123456", + "api_token_0123456789abcdefghijklmnopqrstuv" + ], + "false_positive_patterns": [ + "api_token_example_[a-z]+", + "api_token_demo_[0-9]+" + ] +} +``` + +Custom patterns can detect: +- Internal JWT claim formats +- Proprietary API credential structures +- Database connection string formats +- Microservice authentication tokens +- Legacy system credentials + +Integration with enterprise identity systems: +- Automatically revoke detected secrets from identity provider +- Alert identity team for user authentication review +- Trigger temporary account suspension for high-risk patterns +- Feed detection data to SIEM for correlation with access events + +## Dependency Management + +### Dependabot Overview + +Dependabot is an automated dependency management system that: +- Maintains awareness of all project dependencies and their versions +- Identifies vulnerable versions through CVE databases +- Automatically creates pull requests for security updates and version upgrades +- Monitors for outdated dependencies across the entire dependency tree + +Dependabot operates at three levels: + +**Security Updates**: Automatic PRs when a dependency has a published CVE. These are high-priority and should merge quickly. Enabled by default when Dependabot is active. + +**Version Updates**: Periodic PRs for newer versions of dependencies. Frequency configurable (daily, weekly, monthly). Allows batching non-critical updates. + +**Digest Updates**: For Docker images and other digested dependencies, updates to latest digest even when version remains the same. + +Configuration through `dependabot.yml`: + +```yaml +version: 2 +updates: + # Java/Maven dependencies + - package-ecosystem: "maven" + directory: "/" + schedule: + interval: "daily" + time: "03:00" + security-updates-only: false + commit-message: + prefix: "deps:" + pull-request-branch-name: + separator: "/" + reviewers: + - "platform-team" + assignees: + - "tech-lead" + labels: + - "dependencies" + - "java" + + # Python dependencies + - package-ecosystem: "pip" + directory: "/app" + schedule: + interval: "weekly" + day: "monday" + allow: + - dependency-type: "production" + - dependency-type: "indirect" + ignore: + - dependency-name: "numpy" + versions: [">1.20"] + + # Docker image updates + - package-ecosystem: "docker" + directory: "/docker" + schedule: + interval: "daily" + registries: + - docker-hub + + # GitHub Actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "monthly" +``` + +### Dependency Review and Governance + +Dependency review gates pull request merging based on vulnerability criteria: + +- **Blocking Criteria**: Automatic block if PR introduces high or critical vulnerabilities +- **Advisory Criteria**: Comment on PR with medium and low severity vulnerabilities for developer awareness +- **License Compliance**: Flag dependencies with incompatible licenses (GPL vs MIT, etc.) +- **Supply Chain Risk**: Flag dependencies with unusual maintainer changes, deprecated status, or unusual activity + +GitHub's Dependency Review API enables custom governance policies: + +```yaml +- name: Dependency Review + uses: actions/dependency-review-action@v3 + with: + fail-on-severity: high + allow-licenses: | + MIT + Apache-2.0 + ISC + deny-licenses: | + GPL-2.0 + LGPL-2.1 + vulnerability-check: true + license-check: true + comment-summary-in-pr: true +``` + +### Dependency Graph Architecture + +The dependency graph builds a complete map of an organization's dependencies: + +``` +Repository Dependencies +├── Direct Dependencies (explicitly declared) +│ ├── Production Dependencies +│ │ └── Version constraints, vulnerability status +│ └── Development Dependencies +│ └── Test frameworks, build tools +└── Transitive Dependencies (pulled in by direct deps) + ├── Resolved from manifest/lockfile + └── Nested vulnerability propagation +``` + +Dependency graph capabilities: +- **Manifest Scanning**: Analyzes package manifests (package.json, pom.xml, requirements.txt, etc.) +- **Lockfile Resolution**: Parses lockfiles for exact versions (package-lock.json, yarn.lock, Pipfile.lock) +- **Cross-Repository Dependencies**: Tracks dependencies across multiple repositories within the organization +- **Vulnerability Correlation**: Links dependencies to known vulnerabilities in NVD, GitHub Security Advisories, and ecosystem-specific databases + +The dependency graph powers: +- Automated Dependabot PR creation +- Dependency export APIs for third-party tools +- Organization-level dependency insights +- Supply chain risk scoring + +## Security Policies and Vulnerability Reporting + +### SECURITY.md File + +Organizations should create a standardized SECURITY.md file in each repository describing security practices and incident reporting: + +```markdown +# Security Policy + +## Supported Versions + +| Version | Supported | +|---------|-----------| +| 1.x | :white_check_mark: | +| 0.x | :x: | + +## Reporting a Vulnerability + +We take security very seriously. If you discover a security vulnerability, please email +security@organization.com with: + +- Description of the vulnerability +- Steps to reproduce +- Potential impact +- Suggested remediation (if any) + +**Do not** open a public GitHub issue for security vulnerabilities. + +## Response Expectations + +- Initial response within 24 hours +- Triage complete within 3 business days +- Public advisory or patch release within 30 days of report + +## Security Contact + +- Primary: security@organization.com +- Escalation: ciso@organization.com +- PGP Key: Available at https://organization.com/security.gpg +``` + +### Private Vulnerability Reporting + +Private vulnerability reporting enables external researchers to report security issues through a standardized GitHub flow: + +```mermaid +graph TD + A[Security Researcher] --> B{Has Report Form?} + B -->|Yes| C[Private Vulnerability Report] + B -->|No| D[Email Security Contact] + + C --> E[Create Draft Advisory] + D --> E + + E --> F[Repository Maintainers Notified] + F --> G{Acknowledge Receipt?} + + G -->|Within SLA| H[Begin Investigation] + G -->|Missed SLA| I[Escalate to Security Team] + + H --> J[Develop Patch] + J --> K[Coordinate Embargo Period] + + K --> L[Public Release] + L --> M[Advisory Published] + M --> N[CVE Assigned] + + style C fill:#99ccff + style H fill:#99ff99 + style L fill:#ffcc99 + style N fill:#ff9999 +``` + +Organizations enable private vulnerability reporting through repository settings, allowing external researchers to: +1. Click "Report a vulnerability" in Security tab +2. Provide vulnerability details through guided form +3. Repository maintainers receive notification +4. Discussion occurs in private draft advisory space +5. Patch development proceeds confidentially +6. Public advisory released with CVE upon remediation + +### GitHub Security Advisories + +GitHub Security Advisories are structured records for vulnerabilities affecting publicly available software: + +```json +{ + "cveid": "CVE-2024-12345", + "ghsa": "GHSA-xxxx-yyyy-zzzz", + "summary": "Remote Code Execution in package-name", + "description": "Detailed technical description of vulnerability...", + "severity": "critical", + "affected_versions": [ + { + "range": ">= 1.0.0, < 1.0.5" + }, + { + "range": ">= 2.0.0, < 2.0.3" + } + ], + "patched_versions": ["1.0.5", "2.0.3"], + "identifiers": [ + { + "type": "GHSA", + "value": "GHSA-xxxx-yyyy-zzzz" + }, + { + "type": "CVE", + "value": "CVE-2024-12345" + } + ], + "references": [ + "https://nvd.nist.gov/vuln/detail/CVE-2024-12345" + ], + "published_at": "2024-01-15T10:00:00Z", + "updated_at": "2024-01-15T10:00:00Z", + "withdrawn_at": null, + "cve_metadata_updated_at": "2024-01-15T10:00:00Z" +} +``` + +Advisories provide: +- Automatic correlation with repositories using affected versions +- Dependabot integration for automatic update PR creation +- Export to security databases and vulnerability management systems +- Public searchability for vulnerability intelligence gathering + +## Audit Logging and SIEM Integration + +### Audit Log Architecture + +GitHub Enterprise Cloud maintains comprehensive audit logs of security-relevant events across organizations: + +``` +Audit Log Categories +├── Authentication Events +│ ├── Login/logout +│ ├── Multi-factor authentication events +│ ├── SAML/OIDC authentication +│ └── Token generation/revocation +├── Repository Events +│ ├── Repository creation/deletion +│ ├── Branch protection changes +│ ├── Secret scanning alerts +│ ├── Code scanning findings +│ └── Deployment activity +├── Access Control Events +│ ├── Permission changes +│ ├── Team modifications +│ ├── Organization role changes +│ ├── Deploy key management +│ └── SSH key management +├── Content Events +│ ├── Code pushes +│ ├── Pull request reviews +│ ├── Issue modifications +│ ├── Discussion activity +│ └── Wiki changes +└── Administrative Events + ├── Organization setting changes + ├── Enterprise policy modifications + ├── License changes + ├── SAML identity provider changes + └── Third-party app authorizations +``` + +Audit logs record: +- **Event ID**: Unique identifier for correlation +- **Timestamp**: UTC timestamp with millisecond precision +- **Actor**: User, service account, or application performing action +- **Action**: Specific event type +- **Resource**: Affected repository, organization, or user +- **Result**: Success/failure status with error codes +- **IP Address**: Source IP for network forensics +- **User Agent**: Client information +- **Changes**: Before/after values for modifications +- **Context**: Additional metadata (SAML session ID, API scope, etc.) + +### Audit Log Streaming to SIEM + +GitHub Enterprise Cloud can stream audit logs in real-time to Security Information and Event Management (SIEM) systems: + +**Supported Streaming Protocols**: +- **Syslog over TLS**: Standard syslog protocol with TLS encryption, compatible with most SIEMs +- **Webhook**: HTTPS webhook delivery, best for high-volume environments +- **HTTP API**: Polling API for periodic retrieval + +Configuration example: + +```yaml +# Syslog Streaming Configuration +name: "Production SIEM" +type: "syslog" +server: "siem.organization.com" +port: 6514 +protocol: "tls" +certificate_verification: true +ca_path: "/etc/ssl/certs/organization-ca.pem" +event_batch_size: 500 +retry_policy: "exponential_backoff" +max_retries: 3 +``` + +SIEM integration enables: +- **Centralized Log Aggregation**: All GitHub audit events in one searchable location +- **Real-Time Alerting**: Automated alerts for suspicious patterns (mass deletions, privilege escalation) +- **Correlation Analysis**: Cross-referencing GitHub events with other infrastructure events +- **Compliance Reporting**: Automated evidence collection for audit requirements +- **Forensic Investigation**: Historical analysis of security incidents + +### SIEM Pattern Examples + +**Suspicious Login Pattern Detection**: +``` +event.type = "authentication" AND +event.result = "failure" AND +count(events in 5 minutes) > 10 AND +source.ip NOT IN (known_corporate_networks) +→ Alert: Brute Force Attempt +``` + +**Unauthorized Privilege Escalation**: +``` +event.type = "org.access_change" AND +event.change.permission = "owner" AND +actor.type = "user" AND +actor NOT IN (approved_admins) AND +event.timestamp NOT IN (change_window) +→ Alert: Unauthorized Privilege Change +``` + +**Code Injection Attempt**: +``` +event.type = "push" AND +event.repository.branch = "main" AND +event.files.added > 50 AND +event.files.modified > 100 AND +actor.repository_permissions < "maintain" +→ Alert: Suspicious Mass Commit +``` + +### Compliance Reporting Workflow + +Automated compliance reporting integrates audit logs with reporting systems: + +```mermaid +graph TD + A[GitHub Audit Logs] --> B[SIEM Aggregation] + B --> C[Log Normalization] + C --> D[Compliance Analysis] + + D --> E{Compliance Framework} + E -->|SOC 2| F[Access Controls Report] + E -->|ISO 27001| G[Information Security Report] + E -->|GDPR| H[Data Processing Report] + E -->|HIPAA| I[Audit Trail Report] + + F --> J[Automated Report Generation] + G --> J + H --> J + I --> J + + J --> K[Evidence Collection] + K --> L[Audit Ready Artifacts] + L --> M[Compliance Dashboard] + + style A fill:#e1f5ff + style J fill:#99ff99 + style L fill:#ffcc99 + style M fill:#99ccff +``` + +Monthly compliance reports automatically: +1. **Collect Evidence**: Pull audit log entries matching compliance criteria +2. **Normalize Data**: Convert GitHub events to compliance framework terminology +3. **Analyze Patterns**: Detect anomalies or policy violations +4. **Generate Artifacts**: Create timestamped evidence packages +5. **Store Immutably**: Archive reports for audit retention +6. **Alert on Violations**: Notify compliance team of policy failures + +## Compliance Certifications + +### SOC 2 Type II + +GitHub Enterprise Cloud maintains SOC 2 Type II certification, demonstrating compliance with security, availability, processing integrity, confidentiality, and privacy criteria. + +**Controls Addressed**: +- **CC1-CC9**: Control environment and risk management +- **C1-C2**: Logical access controls +- **S1**: Segregation of duties in development and production +- **PI1**: Policies for preventing unauthorized access to user data +- **PV1**: Privacy policies alignment with GDPR, CCPA + +**Relevant for Organizations**: +- Processing customer data in software +- Subject to vendor security assessments +- Requiring vendor attestation for compliance programs + +### ISO 27001 / 27018 + +GitHub maintains ISO/IEC 27001 certification (information security management) and 27018 (cloud PII protection). + +**Requirements Addressed**: +- **Annex A.5-A.8**: Organization of information security +- **Annex A.9-A.10**: Asset management and access control +- **Annex A.11-A.14**: Physical/technical security, operations, communications +- **Annex A.18**: Compliance with legal and regulatory requirements +- **ISO 27018 Cloud PII**: Specific protections for personally identifiable information processing + +**Enterprise Implications**: +- Evidence of information security management system maturity +- Third-party validation of privacy controls for EU organizations +- Compliance with customer requirements for ISO 27001-certified vendors + +### FedRAMP + +FedRAMP (Federal Risk and Authorization Management Program) provides standardized compliance framework for cloud services used by U.S. government agencies. + +GitHub Cloud for Government meets FedRAMP Moderate baseline requirements: +- **Moderate baseline controls**: 325 security controls from NIST SP 800-53 +- **Authority to Operate (ATO)**: Issued by JAB (Joint Authorization Board) +- **Continuous monitoring**: Annual reassessment with monthly compliance reviews +- **Government-specific network isolation**: Segregated infrastructure for government customers + +**Compliance Domains**: +- Access Control (AC): 22 controls +- Identification and Authentication (IA): 8 controls +- System Communications Protection (SC): 20 controls +- Audit and Accountability (AU): 12 controls +- Security Assessment and Authorization (CA): 8 controls +- Contingency Planning (CP): 13 controls +- Configuration Management (CM): 9 controls + +### Additional Certifications + +**HIPAA Business Associate Agreement (BAA)**: +- Healthcare organizations can execute Business Associate Agreement with GitHub +- Enables compliance with HIPAA Omnibus Rule for handling Protected Health Information (PHI) +- Includes HIPAA-specific audit log requirements and encryption standards + +**PCI DSS**: +- For payment card processing integration +- GitHub data handling meets PCI DSS 3.2.1 requirements +- Suitable for fintech and e-commerce organizations + +**GDPR Data Processing Agreement (DPA)**: +- Standard contractual clauses for EU data transfers +- Data Processing Agreement specifies data processor obligations +- Compliance with Article 28 and Article 44 requirements + +**CCPA/CPRA**: +- California Consumer Privacy Act and California Privacy Rights Act compliance +- Data deletion capabilities and privacy rights management +- Transparency in data collection and processing + +## Enterprise-Scale Security Implementation + +### Security Architecture at Scale + +Implementing comprehensive security across enterprise organizations requires strategic alignment of technical controls with organizational structure: + +**Security Posture Pyramid**: + +``` + Advanced Threat Detection + (Machine Learning, Behavioral) + / + / + Incident Response + (Playbooks, Automation) + / + / + Vulnerability Management + (Scanning, Prioritization, Remediation) + / + / + Access Control & Identity + (RBAC, MFA, SSO) + / + / + Foundation: Audit Logging & Monitoring +``` + +**Layer 1 - Foundation**: Comprehensive logging of all security-relevant events, enabling retrospective investigation and compliance evidence gathering. + +**Layer 2 - Access Control**: Identity management integration (as described in [Identity and Access Management - Doc 03](./03-identity-access-management.md)) ensures least-privilege access, with enforcement at organization and team levels (as per [Teams and Permissions - Doc 05](./05-teams-permissions.md)). + +**Layer 3 - Vulnerability Management**: GHAS scanning capabilities identify vulnerabilities, which are prioritized and tracked through remediation. + +**Layer 4 - Incident Response**: Automated playbooks detect patterns indicating compromise or policy violation, triggering investigation and response workflows. + +**Layer 5 - Advanced Detection**: Machine learning models detect behavioral anomalies, zero-day attack patterns, and supply chain compromises. + +### Cross-Repository Security Governance + +Security governance operates across repository tiers: + +**Critical Repositories** (Tier 1): +- Application: Production applications, core platform libraries, security infrastructure +- GHAS Policy: All features enabled, mandatory before merge +- Code Review: Minimum 2 approvals, at least one from security team +- Deployment: Automated security gates, production approval required +- Audit: Daily scanning, weekly comprehensive security review + +**Important Repositories** (Tier 2): +- Application: Staging environments, internal tools, development frameworks +- GHAS Policy: Code scanning and secret scanning mandatory, dependency review advisory +- Code Review: Minimum 1 approval +- Deployment: Automated gates with fallback option +- Audit: Weekly scanning, monthly review + +**Standard Repositories** (Tier 3): +- Application: Development branches, experimental projects, archived code +- GHAS Policy: Code scanning and secret scanning enabled, not blocking +- Code Review: Self-approval option for non-production work +- Deployment: Minimal gates +- Audit: Monthly scanning + +### Security Cross-Functional Alignment + +Effective enterprise security requires alignment across teams: + +**Development Teams**: +- Responsibility: Fix code scanning findings, resolve secret alerts, keep dependencies current +- Support: 5-day SLA for critical vulnerabilities, 30-day for medium +- Tools: IDE plugins, local CodeQL validation, pre-commit hooks + +**Platform/DevOps Teams**: +- Responsibility: Deploy and maintain scanning infrastructure, configure audit log streaming, manage deployment security gates +- Support: Infrastructure hardening, secret rotation automation, incident response coordination +- Tools: GitHub Actions runners, webhook handlers, SIEM integration + +**Security Teams**: +- Responsibility: Define vulnerability response policies, review critical findings, monitor audit logs, compliance reporting +- Support: Threat intelligence integration, advanced analysis, policy development +- Tools: Vulnerability management platform, SIEM, threat intelligence feeds + +**Compliance Teams**: +- Responsibility: Map controls to compliance requirements, generate audit reports, manage certifications +- Support: Regulatory interpretation, audit preparation, evidence collection +- Tools: Policy management system, audit evidence repository + +## Security Operations Workflows + +### Vulnerability Remediation Workflow + +Vulnerability detection and remediation follows a structured process: + +```mermaid +graph TD + A[Vulnerability Detected] --> B{Auto Categorize} + B -->|Secret| C[Immediate Revocation] + B -->|Dependency| D[Dependabot PR Created] + B -->|Code Issue| E[Code Scanning Alert] + + C --> F[Audit Trail Entry] + D --> G[Developer Review] + E --> G + + G --> H{Reviewer Decision} + H -->|Fix Required| I[Developer Creates PR] + H -->|False Positive| J[Suppress Alert] + H -->|Accept Risk| K[Risk Acceptance Form] + + I --> L[Code Review & Approval] + J --> M[Mark in System] + K --> M + + L --> N{Pass Security Gate?} + N -->|Yes| O[Merge to Production] + N -->|No| P[Return to Developer] + + P --> I + O --> Q[Verify Remediation] + Q --> R[Alert Closed] + M --> R + + style A fill:#ff9999 + style C fill:#99ff99 + style O fill:#99ff99 + style R fill:#cccccc +``` + +**Detection Phase**: +1. Scanning detects vulnerability (code scanning, secret scanning, or dependency analysis) +2. Alert is automatically categorized by type and severity +3. Affected team is automatically assigned based on CODEOWNERS or repository configuration +4. Alert is surfaced in Security tab with remediation guidance + +**Triage Phase**: +1. Security team or repository maintainer reviews the alert +2. Assesses false positive likelihood +3. Determines business impact and risk tolerance +4. Creates response plan + +**Remediation Phase**: +1. For secrets: Immediate revocation and credential rotation +2. For dependencies: Automatic Dependabot PR or manual update +3. For code issues: Developer creates fix PR with security team review +4. Fix PR undergoes standard code review process +5. Security gates verify remediation effectiveness + +**Closure Phase**: +1. Merged fix is deployed through normal deployment pipeline +2. Verification scanning confirms vulnerability is resolved +3. Alert is automatically closed with remediation evidence link +4. Metrics captured for SLA tracking + +### Incident Response Integration + +Security incidents in GitHub trigger coordinated response: + +**Detection**: SIEM correlation rules identify suspicious patterns in audit logs: +- Mass deletion of repositories or branches +- Unauthorized authentication attempts +- Privilege escalation without approval +- Unusual API token activity +- Code push to critical repositories outside deployment windows + +**Initial Response**: +```yaml +incident_response: + mass_deletion_detected: + trigger: "event.action = 'repo.delete' AND count > 5 AND time_window < 5m" + actions: + - alert_severity: "critical" + - notify: + - security_team + - soc_team + - incident_commander + - auto_response: + - revoke_actor_tokens: true + - lock_actor_account: true + - archive_deleted_repos: true + - evidence_collection: + - capture_audit_logs: "24h_before_and_after" + - snapshot_affected_repos: true + - preserve_git_history: true +``` + +**Investigation Phase**: +1. Determine if action was authorized (check change windows, approvals) +2. Review actor's recent activities in audit log +3. Correlate with other infrastructure events (SIEM cross-reference) +4. Interview team members and approvers +5. Review security controls that failed to prevent + +**Containment Phase**: +1. Temporarily suspend compromised account +2. Rotate credentials used during incident +3. Review and revoke any suspicious OAuth applications +4. Reset MFA for affected users +5. Force re-authentication for active sessions + +**Recovery Phase**: +1. Restore data from backups (deleted repositories, branches) +2. Verify integrity of restored data +3. Review code changes for malicious modifications +4. Patch any exploited vulnerabilities +5. Communicate remediation status to stakeholders + +**Post-Incident**: +1. Complete incident report with timeline +2. Identify control failures and process gaps +3. Implement preventive measures +4. Update incident response playbooks +5. Conduct post-mortem with technical team + +### Continuous Compliance Monitoring + +Continuous monitoring ensures security posture remains compliant: + +**Daily Checks**: +- Monitor code scanning alert volume and age (aging alerts escalate in priority) +- Review secret scanning detections (any push protection bypasses) +- Verify audit log streaming to SIEM (detect streaming failures) +- Check for disabled security features + +**Weekly Checks**: +- Review vulnerability remediation SLA compliance +- Audit dependency update PRs and merge status +- Verify no critical repositories without branch protection +- Review access control changes for policy violations + +**Monthly Checks**: +- Comprehensive security posture assessment +- Compliance control mapping verification +- Generate executive security dashboard +- Security team all-hands review of security metrics + +## References + +### GitHub Advanced Security Documentation +- [GitHub Code Scanning Documentation](https://docs.github.com/en/code-security/code-scanning) +- [CodeQL Query Language Documentation](https://codeql.github.io/docs/) +- [GitHub Secret Scanning Documentation](https://docs.github.com/en/code-security/secret-scanning) +- [GitHub Dependabot Documentation](https://docs.github.com/en/code-security/dependabot) + +### GitHub Enterprise Cloud Security +- [Enterprise Security Documentation](https://docs.github.com/en/enterprise-cloud@latest/admin/security) +- [Audit Log API Reference](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-managing-and-maintaining-your-instance/reviewing-audit-logs-for-your-enterprise) +- [Private Vulnerability Reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability) + +### Compliance and Certifications +- [GitHub Trust Center - Security Certifications](https://www.github.com/security) +- [SOC 2 Type II Report](https://github.com/security/compliance) +- [ISO 27001 Certification](https://github.com/security/compliance) +- [FedRAMP Authorization](https://marketplace.fedramp.gov/) + +### Integration Patterns +- [GitHub Actions Security](https://docs.github.com/en/actions/security-guides) +- [SIEM Integration Best Practices](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-managing-and-maintaining-your-instance/streaming-the-audit-log-for-your-enterprise) +- [GitHub Apps for Security Integration](https://docs.github.com/en/developers/apps) + +### Policy and Process Documentation +- [Document 03: Identity and Access Management](./03-identity-access-management.md) +- [Document 04: Enterprise-Managed Users](./04-enterprise-managed-users.md) +- [Document 05: Teams and Permissions](./05-teams-permissions.md) +- [Document 06: Policy Inheritance Architecture](./06-policy-inheritance.md) +- [Document 07: Repository Governance](./07-repository-governance.md) + +### Industry Standards +- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) +- [OWASP Top 10 Web Application Security Risks](https://owasp.org/www-project-top-ten/) +- [CWE/SANS Top 25 Software Weaknesses](https://cwe.mitre.org/top25/) +- [CVE Numbering Authority Information](https://www.cve.org/) diff --git a/docs/09-best-practices-waf.md b/docs/09-best-practices-waf.md new file mode 100644 index 0000000..24d85cb --- /dev/null +++ b/docs/09-best-practices-waf.md @@ -0,0 +1,3444 @@ +# GitHub Well-Architected Framework: Best Practices and Principles + +## Overview + +The GitHub Well-Architected Framework (WAF) provides a comprehensive set of principles and best practices for designing, implementing, and operating enterprise-scale GitHub environments. This framework enables organizations to build secure, reliable, and efficient software delivery platforms that scale with business growth. + +The GitHub WAF is built on five fundamental pillars that work together to create a holistic approach to software development and delivery. Understanding and implementing these pillars ensures that your GitHub Enterprise deployment meets enterprise requirements while maintaining agility and developer productivity. + +## GitHub WAF Five Pillars + +### 1. Reliability + +**Definition:** The ability of your GitHub environment to perform its intended function correctly and consistently, with mechanisms to recover from failures and meet service level objectives. + +**Core Principles:** +- **High Availability:** Design for 99.9%+ uptime using GitHub Enterprise Cloud or properly configured GHES with high availability replicas +- **Disaster Recovery:** Implement comprehensive backup strategies with tested recovery procedures (RPO < 24 hours, RTO < 4 hours for critical systems) +- **Fault Tolerance:** Build resilience into CI/CD pipelines with automatic retries, fallback strategies, and circuit breakers +- **Monitoring and Observability:** Implement comprehensive logging, metrics collection, and alerting across all GitHub operations + +**Key Practices:** +- Use GitHub Enterprise Cloud for maximum reliability (99.95% SLA) +- Implement repository backup automation using GitHub APIs and third-party tools +- Configure webhook delivery monitoring and automatic retry mechanisms +- Design CI/CD workflows with idempotency and retry logic +- Establish clear incident response procedures for GitHub outages +- Use GitHub Actions caching to reduce external dependencies +- Implement health checks for self-hosted runners with automatic replacement + +### 2. Security + +**Definition:** Protection of information, systems, and assets while delivering business value through risk assessments and mitigation strategies. + +**Core Principles:** +- **Defense in Depth:** Multiple layers of security controls from authentication to code scanning +- **Least Privilege:** Grant minimum necessary permissions using RBAC and custom roles +- **Zero Trust:** Verify explicitly, use least privilege access, and assume breach +- **Shift Left:** Integrate security early in the development lifecycle + +**Key Practices:** +- Enforce SAML SSO with IdP synchronization for all organization members +- Require 2FA/MFA for all users, especially admins and privileged accounts +- Implement IP allow lists for enterprise and organization access +- Use GitHub Advanced Security (GHAS) with code scanning, secret scanning, and dependency review +- Enable push protection to prevent secret commits in real-time +- Configure branch protection rules with required reviews and status checks +- Use environment protection rules with required reviewers for production deployments +- Implement OIDC for workload identity federation (eliminate long-lived credentials) +- Regular security audits using the audit log API and SIEM integration +- Use custom organization roles for fine-grained access control +- Enable Dependabot security updates with automatic merge for low-risk patches + +**See also:** [Security and Compliance](08-security-compliance.md) + +### 3. Operational Excellence + +**Definition:** The ability to support development and run systems effectively, gain insight into operations, and continuously improve supporting processes and procedures. + +**Core Principles:** +- **Infrastructure as Code:** Manage GitHub configurations through code (Terraform, GitHub CLI scripts) +- **Automation First:** Automate repetitive tasks to reduce human error and increase efficiency +- **Continuous Improvement:** Regular retrospectives and optimization of workflows +- **Observable Operations:** Comprehensive monitoring, logging, and alerting + +**Key Practices:** +- Use Terraform or GitHub CLI for infrastructure provisioning and configuration management +- Implement GitOps for managing GitHub settings and policies +- Automate user lifecycle management with SCIM provisioning +- Create standardized repository templates with pre-configured settings +- Establish clear runbooks for common operational tasks +- Use GitHub Actions workflows for self-service operations +- Implement chatops for common GitHub operations +- Regular audit log review and compliance reporting automation +- Establish SLAs for common support requests (repository creation, access grants) +- Use labels and projects for operational tracking and metrics + +### 4. Performance Efficiency + +**Definition:** The ability to use computing resources efficiently to meet system requirements and maintain efficiency as demand changes and technologies evolve. + +**Core Principles:** +- **Optimize CI/CD Pipelines:** Minimize build times through caching, parallelization, and resource optimization +- **Efficient Resource Utilization:** Right-size self-hosted runners and manage hosted runner usage +- **Scalability:** Design systems to handle growth without performance degradation +- **Performance Monitoring:** Track and optimize key performance indicators + +**Key Practices:** +- Use GitHub Actions caching for dependencies and build artifacts +- Implement matrix builds for parallel test execution +- Optimize Docker layer caching in containerized workflows +- Use larger hosted runners for compute-intensive workloads +- Configure self-hosted runner autoscaling (Kubernetes, EC2, AKS) +- Implement workflow concurrency controls to prevent resource contention +- Use path filters and conditional execution to skip unnecessary workflows +- Optimize Git operations (shallow clones, sparse checkouts) +- Monitor and optimize Actions minutes consumption +- Use artifact retention policies to manage storage costs +- Implement incremental builds and selective testing strategies + +### 5. Cost Optimization + +**Definition:** The ability to run systems to deliver business value at the lowest price point while meeting functional and non-functional requirements. + +**Core Principles:** +- **Cost Visibility:** Understand and allocate costs accurately across teams and projects +- **Resource Optimization:** Eliminate waste and right-size resources +- **Usage Monitoring:** Track consumption patterns and identify optimization opportunities +- **Financial Governance:** Establish budgets, alerts, and accountability + +**Key Practices:** +- Monitor GitHub Actions minutes usage by organization and repository +- Implement tagging strategies for cost allocation +- Use self-hosted runners for high-volume workloads to reduce Actions minutes costs +- Configure appropriate artifact and log retention periods +- Optimize GitHub Packages storage usage with cleanup policies +- Review and right-size GitHub Copilot seat assignments +- Use GitHub Advanced Security efficiently with targeted repository enablement +- Implement workflow approval gates for expensive operations +- Regular license utilization audits to remove unused seats +- Use enterprise-level purchasing for volume discounts +- Implement cost allocation reports using the billing API + +**See also:** [Enterprise Hierarchy Design](01-enterprise-hierarchy.md) + +## Pillars Relationship + +```mermaid +graph TB + subgraph "GitHub Well-Architected Framework" + REL[Reliability] + SEC[Security] + OPE[Operational Excellence] + PER[Performance Efficiency] + CST[Cost Optimization] + + OPE -->|Enables| REL + OPE -->|Automates| SEC + OPE -->|Improves| PER + OPE -->|Monitors| CST + + SEC -->|Protects| REL + SEC -->|Governs| PER + + PER -->|Optimizes| CST + PER -->|Supports| REL + + REL -->|Foundation for| PER + + CST -->|Constraints| PER + CST -->|Drives| OPE + end + + style OPE fill:#f9f,stroke:#333,stroke-width:4px + style SEC fill:#bbf,stroke:#333,stroke-width:2px + style REL fill:#bfb,stroke:#333,stroke-width:2px + style PER fill:#fbb,stroke:#333,stroke-width:2px + style CST fill:#ffb,stroke:#333,stroke-width:2px +``` + + +## Enterprise Setup Checklist + +### Phase 1: Foundation (Weeks 1-2) + +- [ ] **Enterprise Account Setup** + - [ ] Create GitHub Enterprise Cloud account + - [ ] Configure enterprise-level settings and policies + - [ ] Set up enterprise billing and payment methods + - [ ] Establish enterprise owner and billing manager roles + - [ ] Configure enterprise-level IP allow lists + +- [ ] **Identity and Access Management** + - [ ] Configure SAML SSO with corporate IdP (Okta, Azure AD, Ping) + - [ ] Enable SCIM provisioning for automated user lifecycle + - [ ] Enforce 2FA/MFA for all enterprise members + - [ ] Create initial team structure aligned with organizational hierarchy + - [ ] Define custom organization roles for fine-grained permissions + +- [ ] **Security Baseline** + - [ ] Enable GitHub Advanced Security at enterprise level + - [ ] Configure secret scanning with custom patterns + - [ ] Enable push protection for secrets + - [ ] Set up audit log streaming to SIEM (Splunk, Azure Sentinel) + - [ ] Configure security advisories and vulnerability reporting + +### Phase 2: Organization Structure (Weeks 3-4) + +- [ ] **Organization Design** + - [ ] Create organizations based on business units or product lines + - [ ] Apply organization naming conventions (e.g., `company-product`, `company-dept`) + - [ ] Configure organization base permissions (read, write, none) + - [ ] Set up organization-level teams and hierarchies + - [ ] Configure organization security and analysis settings + +- [ ] **Policy Implementation** + - [ ] Create and apply repository policies (naming, visibility, features) + - [ ] Configure branch protection rulesets at organization level + - [ ] Set up required workflows for compliance and security scanning + - [ ] Define and enforce merge strategies (squash, merge, rebase) + - [ ] Establish code review requirements (reviewers, approvals) + +**See also:** [Organization Strategies](02-organization-strategies.md), [Policy Inheritance](06-policy-inheritance.md) + +### Phase 3: Repository Standards (Weeks 5-6) + +- [ ] **Repository Templates** + - [ ] Create repository templates for common project types + - [ ] Include standard files (README, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY) + - [ ] Pre-configure branch protection rules and workflows + - [ ] Add issue and PR templates + - [ ] Include standard GitHub Actions workflows + +- [ ] **Repository Governance** + - [ ] Define repository naming conventions by project type + - [ ] Establish repository creation approval process (if needed) + - [ ] Configure repository settings standards (wikis, issues, projects) + - [ ] Set default labels and milestones + - [ ] Configure vulnerability alerts and Dependabot + +### Phase 4: CI/CD Implementation (Weeks 7-10) + +- [ ] **GitHub Actions Setup** + - [ ] Configure organization-level secrets and variables + - [ ] Set up self-hosted runners (if required) with autoscaling + - [ ] Create reusable workflows for common patterns + - [ ] Implement workflow templates for standardization + - [ ] Configure Actions usage limits and policies + +- [ ] **Environment Protection** + - [ ] Create environment definitions (dev, staging, production) + - [ ] Configure environment protection rules and required reviewers + - [ ] Set up environment secrets and variables + - [ ] Implement deployment gates and approval workflows + - [ ] Configure environment-specific branch policies + +### Phase 5: Monitoring and Optimization (Ongoing) + +- [ ] **Observability** + - [ ] Set up audit log monitoring and alerting + - [ ] Configure Actions usage dashboards + - [ ] Implement security scanning dashboards + - [ ] Create cost tracking and allocation reports + - [ ] Set up performance monitoring for workflows + +- [ ] **Continuous Improvement** + - [ ] Establish quarterly review cycles for policies and practices + - [ ] Implement feedback mechanisms for developer experience + - [ ] Regular security posture assessments + - [ ] Cost optimization reviews and adjustments + - [ ] Performance tuning for CI/CD pipelines + +## Organization Design Recommendations + +### Multi-Organization vs. Single Organization + +**Use Multiple Organizations When:** +- **Regulatory Compliance:** Need strict separation for compliance (HIPAA, PCI-DSS, FedRAMP) +- **Acquired Companies:** Maintaining separate brand identities or legal entities +- **Geographic Distribution:** Different regional requirements or data residency needs +- **Business Unit Autonomy:** Independent P&L with separate IT governance +- **Security Isolation:** Different security postures or risk profiles + +**Use Single Organization When:** +- **Centralized Governance:** Consistent policies and standards across all teams +- **Resource Sharing:** Common workflows, secrets, and Actions across teams +- **Simplified Management:** Easier administration and lower operational overhead +- **Cross-Team Collaboration:** Frequent collaboration and code sharing +- **Cost Efficiency:** Centralized billing and license management + +### Organization Naming Conventions + +``` +- # Example: acme-retail, acme-healthcare +- # Example: acme-us, acme-eu +- # Example: acme-prod, acme-nonprod (discouraged) +- # Example: acme-platform, acme-mobile +``` + +**Best Practice:** Use business unit or product-based organizations rather than environment-based. Environments should be managed within repositories using environment protection rules. + +### Team Structure Hierarchy + +```mermaid +graph TD + ORG[Organization: acme-platform] + + ORG --> PARENT1[Parent Team: Engineering] + ORG --> PARENT2[Parent Team: Security] + ORG --> PARENT3[Parent Team: Operations] + + PARENT1 --> CHILD1[Child Team: Backend] + PARENT1 --> CHILD2[Child Team: Frontend] + PARENT1 --> CHILD3[Child Team: Mobile] + + PARENT2 --> CHILD4[Child Team: AppSec] + PARENT2 --> CHILD5[Child Team: InfraSec] + + PARENT3 --> CHILD6[Child Team: SRE] + PARENT3 --> CHILD7[Child Team: DevOps] + + CHILD1 --> REPO1[Repository: api-service] + CHILD2 --> REPO2[Repository: web-app] + CHILD4 --> REPO3[Repository: security-tools] + + style ORG fill:#e1f5ff + style PARENT1 fill:#fff4e1 + style PARENT2 fill:#fff4e1 + style PARENT3 fill:#fff4e1 + style CHILD1 fill:#f0f0f0 + style CHILD2 fill:#f0f0f0 + style CHILD3 fill:#f0f0f0 +``` + +**Key Principles:** +- **Nested Teams:** Use parent-child relationships to mirror organizational structure +- **Team Synchronization:** Sync teams with IdP groups using SCIM or team sync +- **Role Assignment:** Assign teams to repositories with appropriate roles (read, triage, write, maintain, admin) +- **Least Privilege:** Start with minimal permissions and grant additional access as needed +- **Team Maintainers:** Designate team maintainers for self-service management + + +## Repository Naming and Structure Conventions + +### Naming Strategy by Project Type + +Consistent naming conventions improve discoverability, reduce confusion, and enable automated management through tooling. Implement naming conventions at the organization level through repository creation policies. + +#### Microservices + +``` +-[-] + +Examples: +- platform-auth-service +- platform-api-gateway +- platform-notification-service +- e-commerce-payment-processor-v2 +- e-commerce-order-fulfillment-sandbox +``` + +**Structure Example:** +``` +platform-auth-service/ +├── .github/ +│ ├── workflows/ +│ │ ├── ci.yml +│ │ ├── security-scan.yml +│ │ └── deploy.yml +│ ├── ISSUE_TEMPLATE/ +│ └── PULL_REQUEST_TEMPLATE/ +├── src/ +│ ├── main/ +│ ├── test/ +│ └── integration/ +├── config/ +│ ├── kubernetes/ +│ ├── helm/ +│ └── terraform/ +├── docs/ +│ ├── api/ +│ ├── architecture/ +│ └── deployment/ +├── Dockerfile +├── docker-compose.yml +├── Makefile +├── README.md +├── CONTRIBUTING.md +└── .gitignore +``` + +#### Frontend Applications + +``` +--ui + +Examples: +- platform-web-ui +- platform-mobile-ui-ios +- platform-mobile-ui-android +- customer-portal-ui +``` + +**Structure Example:** +``` +platform-web-ui/ +├── .github/workflows/ +├── public/ +├── src/ +│ ├── components/ +│ ├── pages/ +│ ├── services/ +│ ├── hooks/ +│ ├── context/ +│ └── __tests__/ +├── scripts/ +├── config/ +│ ├── dev.env +│ ├── staging.env +│ └── prod.env +├── package.json +├── webpack.config.js +├── README.md +└── docker-compose.yml +``` + +#### Shared Libraries + +``` +--lib- + +Examples: +- platform-logging-lib-python +- platform-auth-lib-dotnet +- platform-common-lib-js +- shared-utils-lib-go +``` + +**Structure Example:** +``` +platform-common-lib-js/ +├── .github/workflows/ +│ ├── test.yml +│ ├── publish.yml +│ └── release.yml +├── src/ +│ ├── utils/ +│ ├── validators/ +│ └── formatters/ +├── __tests__/ +├── docs/ +│ ├── API.md +│ └── CHANGELOG.md +├── examples/ +├── package.json +├── tsconfig.json +├── jest.config.js +└── README.md +``` + +#### Infrastructure and DevOps + +``` +-- + +Examples: +- platform-terraform-aws +- platform-helm-charts +- platform-docker-images +- platform-ansible-playbooks +- infrastructure-as-code-prod +``` + +**Structure Example:** +``` +platform-terraform-aws/ +├── .github/workflows/ +│ ├── validate.yml +│ ├── plan.yml +│ └── apply.yml +├── modules/ +│ ├── networking/ +│ ├── compute/ +│ ├── storage/ +│ └── rds/ +├── environments/ +│ ├── dev/ +│ ├── staging/ +│ └── production/ +├── scripts/ +├── docs/ +├── terraform.tfvars +├── main.tf +├── variables.tf +├── outputs.tf +└── README.md +``` + +#### Documentation and Knowledge Base + +``` +-docs + +Examples: +- platform-docs +- architecture-decision-records +- runbooks +``` + +#### Tools and Utilities + +``` +-tools- + +Examples: +- platform-tools-migration +- platform-tools-performance-profiler +- platform-tools-security-scanner +``` + +### Repository Directory Structure Standards + +All repositories should follow this common structure: + +``` +repository-name/ +├── .github/ +│ ├── workflows/ # GitHub Actions workflows +│ ├── ISSUE_TEMPLATE/ # Issue templates +│ └── PULL_REQUEST_TEMPLATE/ +├── src/ # Source code +├── test/ or tests/ # Test files +├── docs/ # Documentation +├── config/ # Configuration files +├── scripts/ # Build and deployment scripts +├── .gitignore +├── .gitattributes +├── README.md +├── CONTRIBUTING.md +├── CODE_OF_CONDUCT.md +├── SECURITY.md +├── LICENSE +└── CHANGELOG.md +``` + +**Cross-reference:** See [Repository Governance](07-repository-governance.md) for enforcement strategies. + +--- + +## Branching Strategy Recommendations + +### Strategy Comparison: GitFlow vs GitHub Flow vs Trunk-Based Development + +```mermaid +graph LR + subgraph "Branch Strategies" + subgraph "GitFlow" + GF1["main (production)"] + GF2["develop (integration)"] + GF3["feature/... (work)"] + GF4["release/... (pre-prod)"] + GF5["hotfix/... (emergency)"] + GF1 ---|merge| GF2 + GF2 ---|branch| GF3 + GF2 ---|branch| GF4 + GF1 ---|branch| GF5 + end + + subgraph "GitHub Flow" + GH1["main (always deployable)"] + GH2["feature/... (temporary)"] + GH1 ---|PR| GH2 + GH2 ---|merge| GH1 + end + + subgraph "Trunk-Based" + TB1["main (stable)"] + TB2["short-lived branches"] + TB3["feature flags"] + TB1 ---|daily commits| TB2 + TB2 ---|merge daily| TB1 + TB1 ---|controls visibility| TB3 + end + end + + style GF1 fill:#e8f5e9 + style GH1 fill:#e8f5e9 + style TB1 fill:#e8f5e9 + style GF2 fill:#fff9c4 + style GH2 fill:#fff9c4 + style TB2 fill:#fff9c4 +``` + +### Strategy Selection Matrix + +| Factor | GitFlow | GitHub Flow | Trunk-Based | +|--------|---------|------------|-------------| +| **Complexity** | High | Low | Medium | +| **Release Cadence** | Planned releases | Continuous deployment | Continuous deployment | +| **Learning Curve** | Steep | Gradual | Medium | +| **Team Size** | Large (50+) | Small-Medium (5-25) | Any size | +| **Best For** | Versioned products | SaaS, web apps | Rapid iteration | +| **Hotfix Handling** | Dedicated branch | PR from main | Immediate fix on main | +| **QA Window** | Release branch | Pre-merge checks | Feature flags | + +### Recommended: GitHub Flow for Most Teams + +**GitHub Flow Workflow:** + +```mermaid +graph LR + A["Create feature branch
from main"] --> B["Commit changes"] + B --> C["Push to remote"] + C --> D["Open Pull Request"] + D --> E["Code Review &
Status Checks"] + E --> F{"Approved?"} + F -->|No| G["Request Changes"] + G --> B + F -->|Yes| H["Merge to main"] + H --> I["Auto-deploy to
staging/prod"] + I --> J["Monitor &
Alert"] + J --> K["Close PR"] + + style A fill:#e3f2fd + style D fill:#fff9c4 + style H fill:#e8f5e9 + style I fill:#f0f4c3 + style K fill:#c8e6c9 +``` + +**Best Practices:** +- Branch naming: `feature/JIRA-123-description`, `fix/JIRA-456-description` +- Keep branches short-lived (< 3 days) +- Squash merge to main for clean history +- Tag releases on main: `v1.2.3` +- Use semantic versioning (MAJOR.MINOR.PATCH) + +### Branch Protection Rules + +Enforce protection at the organization level using rulesets: + +```yaml +# Configured via GitHub API or UI +Protection Rules: + - Branch: main + - Require pull request reviews (minimum 2) + - Require code owner reviews + - Require status checks to pass (CI, security scan) + - Require branches to be up to date + - Require conversation resolution before merge + - Include admins in restrictions + - Restrict who can push to matching branches + + - Branch: develop + - Require pull request reviews (minimum 1) + - Require status checks to pass (CI) + - Allow bypasses for release managers only +``` + +**Cross-reference:** See [Policy Inheritance](06-policy-inheritance.md) for organization-wide enforcement. + +--- + +## CI/CD Governance Best Practices + +### CI/CD Governance Flow + +```mermaid +graph TD + A["Commit to Feature Branch"] --> B["Trigger GitHub Actions"] + B --> C["Run Security Scans"] + C --> D{"Security
Clear?"} + D -->|No| E["Fail & Notify"] + E --> F["Developer Reviews
Findings"] + D -->|Yes| G["Run Unit Tests"] + G --> H{"Tests
Pass?"} + H -->|No| I["Fail & Report"] + I --> F + H -->|Yes| J["Build & Push Image"] + J --> K["Deploy to Dev"] + K --> L["Integration Tests"] + L --> M{"Tests
Pass?"} + M -->|No| I + M -->|Yes| N["Create Pull Request"] + N --> O["Manual Review Gate"] + O --> P{"Approved?"} + P -->|No| Q["Request Changes"] + Q --> F + P -->|Yes| R["Deploy to Staging"] + R --> S["Smoke Tests"] + S --> T{"Manual
Approval?"} + T -->|No| U["Block Deployment"] + T -->|Yes| V["Deploy to Production"] + V --> W["Monitor & Alert"] + W --> X["Rollback Available"] + + style A fill:#e3f2fd + style B fill:#bbdefb + style C fill:#f8bbd0 + style V fill:#c8e6c9 + style X fill:#ffccbc +``` + +### GitHub Actions Governance + +**Workflow Standardization:** + +```yaml +# .github/workflows/ci.yml - Organization standard +name: CI Pipeline + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + +env: + REGISTRY: ghcr.io + +jobs: + security: + runs-on: ubuntu-latest + permissions: + security-events: write + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run CodeQL + uses: github/codeql-action/init@v2 + with: + languages: ['javascript', 'python'] + + - name: Run Secret Scanning + uses: trufflesecurity/trufflehog@main + with: + path: ./ + base: ${{ github.event.repository.default_branch }} + head: HEAD + + - name: CodeQL Analysis + uses: github/codeql-action/analyze@v2 + + test: + runs-on: ubuntu-latest + needs: security + strategy: + matrix: + node-version: [18.x, 20.x] + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v3 + with: + node-version: ${{ matrix.node-version }} + cache: 'npm' + + - run: npm ci + - run: npm run lint + - run: npm run test -- --coverage + - run: npm run build + + deploy: + runs-on: ubuntu-latest + needs: test + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + environment: production + steps: + - uses: actions/checkout@v4 + - name: Deploy to production + run: | + echo "Deploying to production..." + # Add deployment logic +``` + +**Governance Controls:** + +```yaml +# .github/workflows/governance.yml +name: Governance Checks + +on: [pull_request] + +jobs: + check-policies: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Verify file changes + run: | + # Prevent changes to critical files without approval + if git diff --name-only origin/main HEAD | grep -E '(\.github/workflows|package.json|Dockerfile)'; then + echo "Critical files modified - requires senior review" + exit 0 # Require status check in branch protection + fi + + - name: Check branch naming + run: | + BRANCH=${GITHUB_HEAD_REF} + if ! [[ $BRANCH =~ ^(feature|fix|hotfix|release)/ ]]; then + echo "Branch must follow naming convention: feature/*, fix/*, hotfix/*, release/*" + exit 1 + fi + + - name: Verify CHANGELOG updated + run: | + if ! git diff origin/main HEAD | grep -q "CHANGELOG.md"; then + echo "CHANGELOG.md must be updated" + exit 1 + fi +``` + +### Required Status Checks Configuration + +```python +# GitHub API: Set required status checks on main branch +{ + "context": [ + "Security / CodeQL Analysis", + "Security / Secret Scanning", + "Test / Unit Tests (18.x)", + "Test / Unit Tests (20.x)", + "Test / Build", + "Governance / Policies", + "Code Quality / Code Coverage" + ], + "strict": true, # Branch must be up to date + "enforce_admins": true +} +``` + +### Deployment Approval Gates + +```yaml +# Environment protection rules in GitHub +Environments: + - dev: + protection_rules: + - type: none + - deployment_branches: "nonexistent" # Any branch can deploy + + - staging: + protection_rules: + - type: required_reviewers + reviewers: + - teams: [platform/devops, platform/sre] + - minimum: 1 + - deployment_branches: "main" + + - production: + protection_rules: + - type: required_reviewers + reviewers: + - teams: [platform/devops, platform/release-managers] + - minimum: 2 + - deployment_branches: "main" + - custom_deployment_protection_rules: + - timeout_minutes: 15 +``` + +**Cross-reference:** See [Security and Compliance](08-security-compliance.md) for security scanning details. + +--- + +## Change Management Processes + +### Change Management PR Workflow + +```mermaid +graph LR + A["Developer
Starts Work"] --> B["Create Feature Branch"] + B --> C["Commit &
Push Changes"] + C --> D["Open Pull Request"] + D --> E["Automated Checks
Run"] + E --> F{"Checks
Pass?"} + F -->|No| G["View Failures"] + G --> H["Fix Issues"] + H --> C + F -->|Yes| I["Notify Reviewers"] + I --> J["Code Review"] + J --> K{"Review
Approved?"} + K -->|Request Changes| L["Address Feedback"] + L --> C + K -->|Approved| M["Review Dependencies"] + M --> N{"Safe to
Merge?"} + N -->|No| O["Plan Migration"] + O --> L + N -->|Yes| P["Merge to Main"] + P --> Q["Trigger Release
Pipeline"] + Q --> R["Deploy to Staging"] + R --> S["Automated Tests"] + S --> T{"Tests
Pass?"} + T -->|No| U["Rollback &
Investigate"] + U --> V["Post-Mortem"] + T -->|Yes| W["Manual Sign-off"] + W --> X{"Release
Approved?"} + X -->|No| Y["Defer Release"] + X -->|Yes| Z["Deploy to
Production"] + + style A fill:#e3f2fd + style D fill:#fff9c4 + style P fill:#e8f5e9 + style Z fill:#c8e6c9 + style U fill:#ffccbc +``` + +### Pull Request Standards + +**PR Title Format:** +``` +[TYPE] #JIRA-123: Brief description + +Types: +- [FEATURE]: New functionality +- [FIX]: Bug fix +- [REFACTOR]: Code restructuring +- [DOCS]: Documentation only +- [PERF]: Performance improvement +- [TEST]: Test coverage improvement +- [CHORE]: Build, CI, dependencies +``` + +**PR Template (.github/PULL_REQUEST_TEMPLATE/pull_request_template.md):** + +```markdown +## Description +Brief summary of changes and why they're needed. + +## Related Issues +Fixes #JIRA-123 +Related to #JIRA-456 + +## Type of Change +- [ ] Feature +- [ ] Bug Fix +- [ ] Breaking Change +- [ ] Documentation +- [ ] Performance Improvement + +## Testing Done +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Manual testing completed +- [ ] Test coverage maintained (>85%) + +## Checklist +- [ ] Code follows style guidelines +- [ ] Self-review completed +- [ ] Comments added for complex logic +- [ ] Documentation updated +- [ ] No new warnings generated +- [ ] Dependencies updated and audited +- [ ] CHANGELOG.md updated + +## Screenshots/Demos +[Add if applicable] + +## Deployment Notes +[Add any special deployment considerations] + +## Rollback Plan +[Describe how to revert if needed] +``` + +### Code Review Standards + +**Review Checklist:** + +```yaml +# .github/code-review-guidelines.md +Code Review Checklist: + Functionality: + - [ ] Changes implement the intended feature/fix + - [ ] No unnecessary complexity introduced + - [ ] Error handling is appropriate + - [ ] Edge cases are handled + + Quality: + - [ ] Code follows project conventions + - [ ] Naming is clear and descriptive + - [ ] Functions are reasonably sized + - [ ] Comments explain "why" not "what" + + Testing: + - [ ] Test coverage is adequate + - [ ] Tests are meaningful + - [ ] Edge cases tested + - [ ] No flaky tests introduced + + Performance: + - [ ] No obvious performance issues + - [ ] N+1 query problems avoided + - [ ] Memory leaks prevented + + Security: + - [ ] No hardcoded secrets + - [ ] Input validation present + - [ ] SQL injection/XSS prevention + - [ ] OWASP top 10 not violated + + Documentation: + - [ ] README updated if needed + - [ ] API changes documented + - [ ] Breaking changes called out + - [ ] CHANGELOG updated +``` + +### Change Categories and Approval Requirements + +```yaml +Change Categories: + + Routine: + description: "Low-risk changes (docs, tests, small refactors)" + approvals_required: 1 + deployment_wait: none + rollback_plan: "Optional" + + Standard: + description: "Normal features and bug fixes" + approvals_required: 2 + deployment_wait: "Staging soak: 4 hours" + rollback_plan: "Required" + notification: "Notify #deployments channel" + + High-Impact: + description: "Major features, database migrations, security changes" + approvals_required: 3 + deployment_wait: "Staging soak: 24 hours" + rollback_plan: "Required + dry-run" + notification: "Notify leadership + #deployments" + testing: "Security review + load testing" + + Emergency/Hotfix: + description: "Production outages, critical security fixes" + approvals_required: 2 + deployment_wait: "none" + rollback_plan: "Pre-prepared" + notification: "Real-time + incident channel" + post_action: "Post-mortem required" +``` + +### Change Window Management + +```yaml +# .github/workflows/deployment-schedule.yml +name: Change Window Enforcement + +on: + workflow_dispatch: + inputs: + environment: + description: 'Target environment' + required: true + type: choice + options: + - staging + - production + +jobs: + check-window: + runs-on: ubuntu-latest + steps: + - name: Check change window + run: | + HOUR=$(date +%H) + DAY=$(date +%u) + + # Production changes: Tue-Thu, 09:00-17:00 UTC + if [[ "${{ github.event.inputs.environment }}" == "production" ]]; then + if [[ $DAY -lt 2 || $DAY -gt 4 || $HOUR -lt 9 || $HOUR -gt 17 ]]; then + echo "Production deployments outside change window" + exit 1 + fi + fi + + echo "✓ Within approved change window" +``` + +**Cross-reference:** See [Repository Governance](07-repository-governance.md) for policy enforcement. + +--- + +## Disaster Recovery and Backup Strategies + +### Backup Scope and Requirements + +| Asset | RTO | RPO | Backup Frequency | Method | +|-------|-----|-----|------------------|--------| +| **Repositories** | 4 hours | < 1 hour | Hourly | GitHub API snapshots | +| **Configuration** | 2 hours | < 30 min | Every 30 min | GitOps repository | +| **Secrets** | 1 hour | < 15 min | Every 15 min | Vault snapshots | +| **Audit Logs** | 24 hours | < 1 hour | Hourly | SIEM export | +| **Webhooks** | 4 hours | < 1 hour | Hourly | API registry | +| **Team Data** | 8 hours | < 1 hour | Daily | SCIM logs | + +### Repository Backup Automation + +**Python backup script:** + +```python +#!/usr/bin/env python3 +""" +GitHub Enterprise Repository Backup Script +Backs up all repositories in an organization to S3 +""" + +import os +import subprocess +import json +import boto3 +from datetime import datetime +from concurrent.futures import ThreadPoolExecutor, as_completed +import logging + +logging.basicConfig(level=logging.INFO) +logger = logging.getLogger(__name__) + +class RepositoryBackup: + def __init__(self, org_name, s3_bucket, github_token): + self.org_name = org_name + self.s3_bucket = s3_bucket + self.github_token = github_token + self.s3_client = boto3.client('s3') + self.timestamp = datetime.utcnow().isoformat() + + def get_repositories(self): + """Fetch all repositories in organization""" + cmd = [ + 'gh', 'repo', 'list', self.org_name, + '--json', 'nameWithOwner,isPrivate,description', + '--limit', '1000' + ] + + result = subprocess.run( + cmd, + capture_output=True, + text=True, + env={**os.environ, 'GH_TOKEN': self.github_token} + ) + + if result.returncode != 0: + raise Exception(f"Failed to fetch repos: {result.stderr}") + + return json.loads(result.stdout) + + def backup_repository(self, repo_name): + """Backup single repository with all metadata""" + try: + logger.info(f"Backing up {repo_name}") + + # Create temporary directory for backup + backup_dir = f"/tmp/backup-{repo_name.replace('/', '-')}" + os.makedirs(backup_dir, exist_ok=True) + + # Mirror clone (includes all branches and tags) + clone_cmd = [ + 'git', 'clone', '--mirror', + f'https://{self.github_token}@github.com/{repo_name}.git', + f'{backup_dir}/repo.git' + ] + + subprocess.run(clone_cmd, check=True, capture_output=True) + + # Fetch repository metadata + meta_cmd = [ + 'gh', 'repo', 'view', repo_name, + '--json', 'description,homepage,topics,defaultBranchRef,parent,visibility' + ] + + result = subprocess.run( + meta_cmd, + capture_output=True, + text=True, + env={**os.environ, 'GH_TOKEN': self.github_token} + ) + + metadata = json.loads(result.stdout) + + # Save metadata + with open(f'{backup_dir}/metadata.json', 'w') as f: + json.dump(metadata, f, indent=2) + + # Create tarball + tar_path = f"{backup_dir}.tar.gz" + subprocess.run( + ['tar', '-czf', tar_path, '-C', '/tmp', f'backup-{repo_name.replace("/", "-")}'], + check=True, + capture_output=True + ) + + # Upload to S3 + s3_key = f"backups/{self.org_name}/{self.timestamp}/{repo_name}.tar.gz" + + self.s3_client.upload_file( + tar_path, + self.s3_bucket, + s3_key, + ExtraArgs={ + 'ServerSideEncryption': 'AES256', + 'Metadata': { + 'backup-date': self.timestamp, + 'repository': repo_name, + 'organization': self.org_name + } + } + ) + + logger.info(f"✓ Backed up {repo_name} to s3://{self.s3_bucket}/{s3_key}") + + # Cleanup + subprocess.run(['rm', '-rf', backup_dir, tar_path], check=True) + + return { + 'repository': repo_name, + 'status': 'success', + 's3_key': s3_key + } + + except Exception as e: + logger.error(f"✗ Failed to backup {repo_name}: {str(e)}") + return { + 'repository': repo_name, + 'status': 'failed', + 'error': str(e) + } + + def run_backup(self, max_workers=5): + """Execute parallel backups""" + repos = self.get_repositories() + logger.info(f"Backing up {len(repos)} repositories") + + results = [] + with ThreadPoolExecutor(max_workers=max_workers) as executor: + futures = { + executor.submit(self.backup_repository, repo['nameWithOwner']): repo + for repo in repos + } + + for future in as_completed(futures): + try: + result = future.result() + results.append(result) + except Exception as e: + logger.error(f"Backup task failed: {str(e)}") + + # Generate report + self.generate_report(results) + return results + + def generate_report(self, results): + """Generate and store backup report""" + successful = len([r for r in results if r['status'] == 'success']) + failed = len([r for r in results if r['status'] == 'failed']) + + report = { + 'timestamp': self.timestamp, + 'organization': self.org_name, + 'total_repositories': len(results), + 'successful': successful, + 'failed': failed, + 'details': results + } + + # Save report to S3 + report_key = f"backups/{self.org_name}/{self.timestamp}/backup-report.json" + self.s3_client.put_object( + Bucket=self.s3_bucket, + Key=report_key, + Body=json.dumps(report, indent=2), + ContentType='application/json' + ) + + logger.info(f"Backup report: {successful} succeeded, {failed} failed") + logger.info(f"Report: s3://{self.s3_bucket}/{report_key}") + +if __name__ == '__main__': + backup = RepositoryBackup( + org_name=os.getenv('GH_ORG'), + s3_bucket=os.getenv('BACKUP_BUCKET'), + github_token=os.getenv('GH_TOKEN') + ) + backup.run_backup() +``` + +### Configuration Backup Script + +```bash +#!/bin/bash +# Backup GitHub organization configuration to Git repository + +set -euo pipefail + +ORG=${GH_ORG:-"acme"} +BACKUP_REPO="git@github.com:${ORG}/${ORG}-infra-backup.git" +TEMP_DIR=$(mktemp -d) + +trap "rm -rf $TEMP_DIR" EXIT + +echo "📦 Backing up organization configuration..." + +# Clone or create backup repository +if git ls-remote "$BACKUP_REPO" &>/dev/null; then + git clone "$BACKUP_REPO" "$TEMP_DIR/backup" +else + mkdir -p "$TEMP_DIR/backup" + cd "$TEMP_DIR/backup" + git init +fi + +cd "$TEMP_DIR/backup" + +# Backup organization settings +echo "Fetching organization settings..." +gh org view "${ORG}" --json "name,description,email,blog,location" \ + > "org-settings.json" + +# Backup teams +echo "Fetching teams..." +gh team list --org "${ORG}" --json "name,slug,description,privacy" \ + > teams.json + +# Backup repositories +echo "Fetching repositories..." +gh repo list "${ORG}" --json "name,description,visibility,isArchived,topics" \ + > repositories.json + +# Backup branch protection rules +echo "Fetching branch protection rules..." +mkdir -p branch-protection-rules +for repo in $(gh repo list "${ORG}" --json "name" --jq ".[].name"); do + gh api "repos/${ORG}/${repo}/rules/branches" > "branch-protection-rules/${repo}.json" 2>/dev/null || true +done + +# Backup webhooks registry +echo "Fetching webhooks..." +mkdir -p webhooks +for repo in $(gh repo list "${ORG}" --json "name" --jq ".[].name"); do + gh api "repos/${ORG}/${repo}/hooks" --jq '.[] | {id, name, events, active}' \ + > "webhooks/${repo}.json" 2>/dev/null || true +done + +# Backup custom roles +echo "Fetching custom roles..." +gh api "orgs/${ORG}/roles/custom_roles" --jq '.[] | {id, name, permissions}' \ + > custom-roles.json 2>/dev/null || true + +# Commit and push +git add -A +git commit -m "Organization backup: $(date -u +'%Y-%m-%d %H:%M:%S UTC')" || true +git push -u origin main 2>/dev/null || git push -u origin master + +echo "✓ Configuration backup complete" +``` + +### Recovery Procedures + +**Repository Recovery:** + +```bash +#!/bin/bash +# Restore a repository from backup + +BACKUP_ARCHIVE=$1 +REPO_NAME=$2 +TARGET_ORG=$3 + +if [[ -z "$BACKUP_ARCHIVE" || -z "$REPO_NAME" || -z "$TARGET_ORG" ]]; then + echo "Usage: $0 " + exit 1 +fi + +echo "�� Restoring repository ${REPO_NAME}..." + +# Extract backup +TEMP_DIR=$(mktemp -d) +trap "rm -rf $TEMP_DIR" EXIT + +tar -xzf "$BACKUP_ARCHIVE" -C "$TEMP_DIR" + +# Read metadata +METADATA=$(cat "$TEMP_DIR/backup-${REPO_NAME}/metadata.json") +DESCRIPTION=$(echo "$METADATA" | jq -r '.description') +VISIBILITY=$(echo "$METADATA" | jq -r '.visibility') + +# Create repository +gh repo create "${TARGET_ORG}/${REPO_NAME}" \ + --description "$DESCRIPTION" \ + --visibility "$VISIBILITY" \ + --source "$TEMP_DIR/backup-${REPO_NAME}/repo.git" \ + --remote origin \ + --push + +echo "✓ Repository restored to github.com/${TARGET_ORG}/${REPO_NAME}" +``` + +### Backup Validation and Testing + +```yaml +# .github/workflows/backup-validation.yml +name: Backup Validation + +on: + schedule: + - cron: '0 2 * * 0' # Weekly + +jobs: + validate-backups: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Download latest backups + run: | + aws s3 sync s3://${{ secrets.BACKUP_BUCKET }}/backups/${{ secrets.ORG }}/ \ + ./backups/ \ + --exclude "*" \ + --include "$(date +%Y-%m-%d)/*" \ + --region us-east-1 + + - name: Validate backup integrity + run: | + for backup in backups/*/*.tar.gz; do + echo "Validating $backup..." + tar -tzf "$backup" > /dev/null || exit 1 + echo "✓ $backup valid" + done + + - name: Test repository restore + run: | + # Extract and verify a random backup + BACKUP=$(ls -1 backups/*/*.tar.gz | shuf -n 1) + echo "Testing restore of $BACKUP..." + + TEMP_DIR=$(mktemp -d) + tar -xzf "$BACKUP" -C "$TEMP_DIR" + + # Verify git repository + git -C "$TEMP_DIR/*/repo.git" rev-parse HEAD + echo "✓ Repository restore successful" + + - name: Generate validation report + if: always() + run: | + # Generate and upload report + echo "Backup validation report: $(date)" > validation-report.txt + aws s3 cp validation-report.txt \ + s3://${{ secrets.BACKUP_BUCKET }}/validation-reports/$(date +%Y-%m-%d).txt +``` + +**Cross-reference:** See [Security and Compliance](08-security-compliance.md) for encryption and access control. + +--- + +## Enterprise Maturity Model + +### Five-Level Maturity Framework + +```mermaid +graph TD + L1["Level 1: Foundational"] --> L2["Level 2: Standardized"] + L2 --> L3["Level 3: Managed"] + L3 --> L4["Level 4: Optimized"] + L4 --> L5["Level 5: Innovating"] + + L1 --> L1D["Manual processes
Limited governance
Ad-hoc security"] + L2 --> L2D["Documented standards
Basic automation
Initial guardrails"] + L3 --> L3D["Enforced policies
Advanced automation
Continuous monitoring"] + L4 --> L4D["Self-service platforms
AI-assisted workflows
Predictive security"] + L5 --> L5D["Autonomous systems
Continuous innovation
Predictive optimization"] + + style L1 fill:#ffcccc + style L2 fill:#ffe6cc + style L3 fill:#ffffcc + style L4 fill:#e6f2ff + style L5 fill:#ccffcc +``` + +### Level 1: Foundational + +**Characteristics:** +- Manual repository creation and access provisioning +- No consistent naming conventions +- Ad-hoc security practices +- Limited audit capabilities +- Reactive incident response + +**Maturity Indicators:** +- [ ] GitHub Enterprise Cloud account created +- [ ] Basic RBAC configured +- [ ] Limited audit logging +- [ ] Manual backup procedures +- [ ] No formal governance policies + +**Timeline:** 2-4 weeks + +**Estimated Cost:** $50k-$100k setup + +--- + +### Level 2: Standardized + +**Characteristics:** +- Defined repository naming conventions +- Consistent branch strategies +- Basic CI/CD pipelines +- Documented security baseline +- Initial automation + +**Maturity Indicators:** +- [ ] Repository templates implemented +- [ ] Branch protection rules enforced +- [ ] GitHub Actions basic workflows +- [ ] Security scanning enabled +- [ ] Audit logging to centralized system +- [ ] Formal repository governance policy + +**Timeline:** 4-8 weeks + +**Estimated Cost:** $100k-$200k + +**Implementation Focus:** +```yaml +Governance: + - Repository creation policy + - Naming conventions + - Branch protection standards + - Code review requirements + +Security: + - Secret scanning enabled + - Dependabot configured + - SAML SSO enforced + - 2FA requirement + +Automation: + - GitHub Actions setup + - Automated testing + - Build pipelines +``` + +--- + +### Level 3: Managed + +**Characteristics:** +- Automated policy enforcement +- Advanced CI/CD with multiple environments +- Comprehensive security controls +- Real-time monitoring and alerting +- Self-service operations + +**Maturity Indicators:** +- [ ] Rulesets and policy enforcement +- [ ] Advanced GitHub Actions workflows +- [ ] Environment protection rules +- [ ] Custom roles implemented +- [ ] Deployment automation +- [ ] Real-time alerting configured +- [ ] SLA definitions +- [ ] Change management process + +**Timeline:** 8-12 weeks + +**Estimated Cost:** $200k-$400k + +**Implementation Focus:** +```yaml +Governance: + - Rulesets for policy enforcement + - Custom organization roles + - Delegated administration + - Change management process + +CI/CD: + - Multi-environment pipelines + - Automated testing matrix + - Deployment gates + - Rollback procedures + +Operations: + - Dashboards and metrics + - Alert policies + - Runbook automation + - Incident response procedures +``` + +--- + +### Level 4: Optimized + +**Characteristics:** +- AI-assisted security and compliance +- Predictive performance optimization +- Autonomous deployment pipelines +- Cost optimization automation +- Platform as a service for development teams + +**Maturity Indicators:** +- [ ] Machine learning-based anomaly detection +- [ ] Predictive scaling +- [ ] Autonomous deployment gates +- [ ] Cost optimization dashboards +- [ ] Advanced custom workflows +- [ ] Platform self-service portal +- [ ] Continuous optimization cycles + +**Timeline:** 12-20 weeks + +**Estimated Cost:** $400k-$800k + +**Implementation Focus:** +```yaml +Intelligence: + - ML-based security scanning + - Predictive performance metrics + - Anomaly detection + - Usage forecasting + +Automation: + - Autonomous deployment gates + - Self-healing workflows + - Automatic cost optimization + - Predictive scaling + +Platform: + - Self-service developer portal + - GitOps-driven infrastructure + - Automatic compliance reporting +``` + +--- + +### Level 5: Innovating + +**Characteristics:** +- Continuous autonomous innovation +- Predictive governance +- Integrated with AI/ML systems +- Continuous compliance +- Strategic business alignment + +**Maturity Indicators:** +- [ ] Continuous feature delivery +- [ ] Autonomous security response +- [ ] Real-time compliance auditing +- [ ] Predictive business metrics +- [ ] Advanced developer experience +- [ ] Integrated with enterprise AI/ML + +**Timeline:** 20+ weeks + +**Estimated Cost:** $800k-$2M+ + +**Implementation Focus:** +```yaml +Innovation: + - Continuous feature delivery + - AI-driven architecture recommendations + - Predictive capacity planning + - Autonomous security response + +Governance: + - Real-time compliance + - Predictive risk management + - Autonomous policy adjustment + - Strategic alignment automation + +Experience: + - Advanced developer platform + - Integrated AI/ML services + - Predictive issue resolution + - Context-aware recommendations +``` + +### Maturity Assessment Questionnaire + +```yaml +Questions by Category: + +Process Maturity: + 1. How are repositories currently created? (manual/templated/automated) + 2. Are naming conventions enforced? (no/advisory/enforced) + 3. Is CI/CD pipeline standard? (no/basic/advanced) + 4. Are deployments automated? (no/partial/full) + 5. Is there a change management process? (no/documented/enforced) + +Security Maturity: + 1. Is SAML SSO implemented? (no/partial/full) + 2. Is MFA enforced? (no/optional/required) + 3. Are secrets scanned? (no/optional/required) + 4. Is GHAS enabled? (no/some repos/all repos) + 5. Are audit logs centralized? (no/local/SIEM) + +Operational Maturity: + 1. Are operations automated? (manual/partial/full) + 2. Is there centralized monitoring? (no/basic/advanced) + 3. Are SLAs defined? (no/informal/formal) + 4. Is incident response documented? (no/basic/advanced) + 5. Are retrospectives regular? (no/ad-hoc/scheduled) + +Financial Maturity: + 1. Is cost tracking implemented? (no/manual/automated) + 2. Are budgets defined? (no/informal/enforced) + 3. Is usage monitored? (no/manual/automated) + 4. Are optimization efforts planned? (no/ad-hoc/continuous) + 5. Is ROI measured? (no/estimated/measured) +``` + +**Cross-reference:** See [Organization Strategies](02-organization-strategies.md) for organizational alignment. + +--- + +## Scaling Patterns for Large Enterprises + +### Pattern 1: Federated Multi-Organization Model + +**Use When:** +- Organizations > 10,000 developers +- Multiple business units with autonomous governance +- Strict regulatory/compliance requirements +- Geographic distribution requirements + +**Architecture:** +``` +Enterprise +├── acme-platform (shared services) +│ ├── Team: Platform +│ └── Repos: shared-libs, workflows, tools +├── acme-commerce (business unit) +│ ├── Team: Commerce-Backend +│ ├── Team: Commerce-Frontend +│ └── Repos: payment-service, checkout-ui +├── acme-healthcare (business unit) +│ ├── Team: Healthcare-Backend +│ └── Repos: patient-api, records-service +└── acme-infrastructure (DevOps) + ├── Team: SRE + └── Repos: terraform-aws, helm-charts +``` + +**Implementation:** + +```hcl +# Enterprise-level Terraform configuration +terraform { + required_providers { + github = { + source = "integrations/github" + version = "~> 6.0" + } + } +} + +# Create federated organizations +module "commerce_org" { + source = "./modules/organization" + + name = "acme-commerce" + display_name = "ACME Commerce Platform" + billing_email = "commerce-billing@acme.com" + + teams = { + backend = { + privacy = "closed" + members = ["backend-team@acme.com"] + } + frontend = { + privacy = "closed" + members = ["frontend-team@acme.com"] + } + } + + policies = { + require_branch_protection = true + require_code_owners = true + minimum_reviewers = 2 + } +} + +# Create shared services organization +module "platform_org" { + source = "./modules/organization" + + name = "acme-platform" + display_name = "ACME Shared Platform" + billing_email = "platform-billing@acme.com" + + shared_services = true +} +``` + +### Pattern 2: Hub-and-Spoke Monorepo Strategy + +**Use When:** +- Highly interdependent teams +- Monorepo benefits outweigh distributed drawbacks +- Central platform team coordination needed +- Real-time code sharing required + +**Structure:** +``` +monorepo/ +├── services/ +│ ├── auth-service/ +│ ├── api-gateway/ +│ └── payments-service/ +├── packages/ +│ ├── common-lib/ +│ ├── logging-lib/ +│ └── auth-lib/ +├── frontend/ +│ ├── web-app/ +│ └── admin-portal/ +├── infrastructure/ +│ ├── kubernetes/ +│ ├── terraform/ +│ └── helm/ +└── .github/workflows/ + ├── ci-root.yml + ├── ci-services.yml + └── deploy.yml +``` + +**Workflow Implementation:** + +```yaml +# .github/workflows/monorepo-ci.yml +name: Monorepo CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + +env: + REGISTRY: ghcr.io + CACHE_REGISTRY: ttl.sh + +jobs: + detect-changes: + runs-on: ubuntu-latest + outputs: + services: ${{ steps.detect.outputs.services }} + packages: ${{ steps.detect.outputs.packages }} + frontend: ${{ steps.detect.outputs.frontend }} + infrastructure: ${{ steps.detect.outputs.infrastructure }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - id: detect + run: | + # Detect changed directories + BASE=${{ github.event.pull_request.base.sha || 'HEAD~1' }} + HEAD=${{ github.sha }} + + CHANGED=$(git diff --name-only $BASE...$HEAD) + + # Check each path + echo "services=$(echo "$CHANGED" | grep -q '^services/' && echo 'true' || echo 'false')" >> $GITHUB_OUTPUT + echo "packages=$(echo "$CHANGED" | grep -q '^packages/' && echo 'true' || echo 'false')" >> $GITHUB_OUTPUT + echo "frontend=$(echo "$CHANGED" | grep -q '^frontend/' && echo 'true' || echo 'false')" >> $GITHUB_OUTPUT + echo "infrastructure=$(echo "$CHANGED" | grep -q '^infrastructure/' && echo 'true' || echo 'false')" >> $GITHUB_OUTPUT + + build-services: + needs: detect-changes + if: ${{ needs.detect-changes.outputs.services == 'true' }} + runs-on: ubuntu-latest + strategy: + matrix: + service: [auth-service, api-gateway, payments-service] + steps: + - uses: actions/checkout@v4 + - name: Build ${{ matrix.service }} + run: | + cd services/${{ matrix.service }} + docker build -t ${{ env.REGISTRY }}/acme/${{ matrix.service }}:${{ github.sha }} . + docker push ${{ env.REGISTRY }}/acme/${{ matrix.service }}:${{ github.sha }} + + build-frontend: + needs: detect-changes + if: ${{ needs.detect-changes.outputs.frontend == 'true' }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v3 + with: + node-version: 18 + cache: npm + - run: | + npm ci + npm run lint + npm run test + npm run build + - name: Build and push frontend image + run: | + docker build -t ${{ env.REGISTRY }}/acme/web-app:${{ github.sha }} ./frontend/web-app + docker push ${{ env.REGISTRY }}/acme/web-app:${{ github.sha }} + + integration-tests: + needs: [build-services, build-frontend] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run integration tests + run: | + docker-compose -f docker-compose.test.yml up --abort-on-container-exit +``` + +### Pattern 3: Distributed Microservices Model + +**Use When:** +- Autonomous service ownership required +- Different release cadences per service +- Technology diversity needed +- Large number of small teams (50+) + +**Repository Organization:** + +``` +GitHub Enterprise +├── acme-platform-org +│ ├── Platform Services (5-7 repos) +│ ├── Shared Libraries (3-5 repos) +│ ├── Infrastructure (2-3 repos) +│ └── DevOps Tools (2-3 repos) +├── acme-services-org (40+ repos, 1 per service) +│ ├── user-service +│ ├── order-service +│ ├── payment-service +│ ├── shipping-service +│ └── ... (1 repo per autonomously owned service) +├── acme-frontend-org (8-12 repos) +│ ├── web-app-core +│ ├── mobile-app-ios +│ ├── mobile-app-android +│ └── ... (1 repo per frontend app) +└── acme-infrastructure-org + ├── terraform-modules + ├── helm-charts + ├── kubernetes-manifests + └── observability-stack +``` + +**Service Repository Template:** + +```yaml +# service-template/.github/workflows/service-deployment.yml +name: Service Deployment Pipeline + +on: + push: + branches: [main] + tags: ['v*'] + pull_request: + branches: [main] + +env: + SERVICE_NAME: ${{ github.event.repository.name }} + REGISTRY: ghcr.io/${{ github.repository_owner }} + +jobs: + test: + runs-on: ubuntu-latest + services: + postgres: + image: postgres:15 + env: + POSTGRES_PASSWORD: postgres + redis: + image: redis:7 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-go@v4 + with: + go-version: 1.21 + cache: true + + - run: | + go test ./... -v -race -coverprofile=coverage.out + go tool cover -html=coverage.out -o coverage.html + + - uses: codecov/codecov-action@v3 + with: + files: ./coverage.out + + build: + needs: test + if: github.event_name == 'push' + runs-on: ubuntu-latest + outputs: + image-tag: ${{ steps.image.outputs.tag }} + steps: + - uses: actions/checkout@v4 + + - id: image + run: | + if [[ "${{ github.ref }}" == refs/tags/* ]]; then + TAG=${GITHUB_REF#refs/tags/} + else + TAG=${{ github.sha }} + fi + echo "tag=$TAG" >> $GITHUB_OUTPUT + + - uses: docker/build-push-action@v4 + with: + context: . + push: true + tags: ${{ env.REGISTRY }}/${{ env.SERVICE_NAME }}:${{ steps.image.outputs.tag }} + cache-from: type=gha + cache-to: type=gha,mode=max + + deploy: + needs: build + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + runs-on: ubuntu-latest + environment: production + steps: + - uses: actions/checkout@v4 + + - uses: azure/setup-kubectl@v3 + with: + version: 1.27 + + - name: Deploy to Kubernetes + run: | + kubectl set image deployment/${{ env.SERVICE_NAME }} \ + ${{ env.SERVICE_NAME }}=${{ env.REGISTRY }}/${{ env.SERVICE_NAME }}:${{ needs.build.outputs.image-tag }} \ + -n production + + kubectl rollout status deployment/${{ env.SERVICE_NAME }} -n production +``` + +### Pattern 4: Enterprise API Platform + +**Use When:** +- Internal API marketplace needed +- API versioning and governance required +- Cross-organization API consumers +- Revenue-generating APIs + +**Implementation:** + +```bash +# API Platform Structure +api-platform-org/ +├── api-catalog (registry of all APIs) +├── api-gateway (central entry point) +├── api-governance (policies and standards) +├── api-docs (centralized documentation) +├── api-examples (SDKs, samples) +└── api-services/ + ├── users-api + ├── products-api + ├── orders-api + └── ... (one repo per API) +``` + +**API Documentation Portal:** + +```yaml +# .github/workflows/api-docs-build.yml +name: Build API Documentation + +on: + push: + branches: [main] + pull_request: + +jobs: + build-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Aggregate OpenAPI specs + run: | + # Collect OpenAPI specs from all API repos + gh repo list acme-platform-org --json "nameWithOwner" --jq '.[] | select(.nameWithOwner | test("api$")) | .nameWithOwner' | while read repo; do + gh repo clone "$repo" "/tmp/$repo" + if [ -f "/tmp/$repo/openapi.yaml" ]; then + cp "/tmp/$repo/openapi.yaml" "specs/${repo##*/}.yaml" + fi + done + + - name: Generate API documentation + run: | + npx redoc-cli bundle specs/*.yaml -o api-docs.html + + - name: Deploy to API Portal + run: | + aws s3 sync . s3://api-portal/docs/ --exclude "*" --include "api-docs.html" +``` + +### Pattern 5: Multi-Region Deployment + +**Use When:** +- Global deployments required +- Regional compliance needs +- High availability across regions +- Latency optimization + +**Regional Organization Structure:** + +``` +Enterprise +├── acme-global (cross-region shared) +├── acme-us (US region) +│ ├── Resources in us-east-1, us-west-2 +│ ├── US-specific compliance +│ └── Regional SRE team +├── acme-eu (EU region) +│ ├── Resources in eu-west-1, eu-central-1 +│ ├── GDPR compliance +│ └── Regional SRE team +└── acme-apac (Asia-Pacific) + ├── Resources in ap-southeast-1, ap-northeast-1 + ├── Regional compliance + └── Regional SRE team +``` + +**Regional Deployment Workflow:** + +```yaml +# infrastructure/workflows/multi-region-deploy.yml +name: Multi-Region Deployment + +on: + workflow_dispatch: + inputs: + regions: + description: Regions to deploy to + required: true + default: us,eu,apac + type: choice + options: + - us + - eu + - apac + - us,eu + - us,eu,apac + +jobs: + deploy-regions: + strategy: + matrix: + region: ${{ fromJSON(format('["{0}"]', github.event.inputs.regions)) }} + runs-on: ubuntu-latest + environment: production-${{ matrix.region }} + steps: + - uses: actions/checkout@v4 + + - name: Deploy to ${{ matrix.region }} + env: + AWS_REGION: ${{ secrets[format('AWS_REGION_{0}', matrix.region)] }} + run: | + # Deploy to specific region + terraform -chdir=infrastructure/regions/${{ matrix.region }} apply -auto-approve + + - name: Run smoke tests + run: | + ./scripts/smoke-tests.sh ${{ matrix.region }} + + - name: Update traffic weights + run: | + # Gradually shift traffic to new deployment (canary) + ./scripts/canary-deploy.sh ${{ matrix.region }} 5 10 20 50 100 +``` + +**Cross-reference:** See [Organization Strategies](02-organization-strategies.md) for multi-organization patterns. + + +## Common Anti-Patterns to Avoid + +### 1. Unlimited Repository Creation Without Governance + +**Anti-Pattern:** +``` +❌ No repository creation controls +❌ No naming conventions enforced +❌ No consistent structure +❌ Impossible to discover repositories +``` + +**Problem:** +- Repository sprawl and duplication +- Inconsistent configurations +- Security vulnerabilities from misconfigured repos +- Compliance violations +- Difficult cost tracking + +**Solution:** + +```python +# Enforce repository creation through automation +import subprocess +import sys +import re +import json + +def create_repository(org: str, name: str, template: str, **kwargs): + """Create repository from template with validation""" + + # Validate naming convention + valid_patterns = { + 'service': r'^[a-z]+-service$', + 'lib': r'^[a-z]+-lib-[a-z]+$', + 'ui': r'^[a-z]+-ui(-[a-z]+)?$', + } + + repo_type = kwargs.get('type', 'service') + pattern = valid_patterns.get(repo_type) + + if not re.match(pattern, name): + sys.exit(f"❌ Repository name '{name}' doesn't match pattern for type '{repo_type}'") + + # Use template + cmd = [ + 'gh', 'repo', 'create', f'{org}/{name}', + '--template', f'{org}/{template}', + '--visibility', kwargs.get('visibility', 'private'), + '--description', kwargs.get('description', ''), + ] + + subprocess.run(cmd, check=True) + + # Configure branch protection + subprocess.run([ + 'gh', 'api', f'repos/{org}/{name}/branches/main/protection', + '--input', '/dev/stdin' + ], input=json.dumps({ + 'required_pull_request_reviews': {'required_approving_review_count': 1}, + 'required_status_checks': {'strict': True, 'contexts': ['ci', 'security']}, + 'enforce_admins': True + }), check=True) +``` + +--- + +### 2. Secrets Stored in Code or Environment Variables + +**Anti-Pattern:** +```python +❌ API_KEY="sk-12345abcde" # In code +❌ DATABASE_PASSWORD in .env file +❌ SSH keys committed to repository +❌ Credentials in CI/CD logs +``` + +**Problem:** +- Exposed credentials in git history (permanent) +- Leaked secrets in logs +- Compromised integrations +- Regulatory violations +- Difficult remediation + +**Solution:** + +```yaml +# Use GitHub Secrets Management +- name: Deploy with secure credentials + run: | + # ✓ Credentials only in memory, never in logs + export DB_PASSWORD=${{ secrets.DB_PASSWORD }} + export API_KEY=${{ secrets.API_KEY }} + ./deploy.sh + env: + # ✓ Mask sensitive values from logs + ACTIONS_STEP_DEBUG: false + +# Use OIDC for workload identity +- name: Authenticate to AWS + uses: aws-actions/configure-aws-credentials@v2 + with: + role-to-assume: ${{ secrets.AWS_ROLE_ARN }} + aws-region: us-east-1 + # No access keys needed! + +# Use sealed secrets in GitOps +apiVersion: bitnami.com/v1alpha1 +kind: SealedSecret +metadata: + name: app-secrets + namespace: production +spec: + encryptedData: + database-password: AgBv... # Encrypted, safe to commit +``` + +--- + +### 3. Monolithic CI/CD with Long Build Times + +**Anti-Pattern:** +```yaml +❌ All tests run sequentially +❌ Full build on every change +❌ No caching +❌ 45+ minute build time +❌ Developers wait for feedback +``` + +**Problem:** +- Developer productivity loss +- Slow feedback loop +- Build queue backlogs +- Wasted compute resources +- High cost + +**Solution:** + +```yaml +name: Optimized Parallel CI + +on: [push, pull_request] + +jobs: + lint-and-unit-fast: + runs-on: ubuntu-latest + # Run immediately, fail fast + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v3 + with: + node-version: 18 + cache: npm + + - run: npm ci --prefer-offline --no-audit + - run: npm run lint -- --max-warnings 0 + - run: npm run test:unit -- --coverage --forceExit + # Total: 5-7 minutes + + security-scan-parallel: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: github/codeql-action/init@v2 + - uses: github/codeql-action/analyze@v2 + - uses: aquasecurity/trivy-action@master + # Parallel with tests: 10-12 minutes total + + build-and-integration: + needs: [lint-and-unit-fast] # Only run if fast checks pass + runs-on: ubuntu-latest + strategy: + matrix: + node-version: [18.x, 20.x] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v3 + with: + node-version: ${{ matrix.node-version }} + cache: npm + + - run: npm ci --prefer-offline + - run: npm run build + - run: npm run test:integration + # 15-20 minutes, but parallel + + # Total time: 20 minutes vs 45 minutes sequential +``` + +--- + +### 4. No Enforcement of Code Quality Standards + +**Anti-Pattern:** +``` +❌ Code reviews are optional +❌ No automated checks +❌ Anyone can merge without review +❌ Code quality degrades over time +❌ No coverage requirements +``` + +**Problem:** +- Technical debt accumulates +- Bugs reach production +- Security vulnerabilities missed +- Inconsistent code style +- Knowledge silos + +**Solution:** + +```yaml +# .github/workflows/enforce-quality.yml +name: Quality Gate Enforcement + +on: [pull_request] + +permissions: + contents: read + pull-requests: write + +jobs: + enforce-standards: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + # Prevent merge without required reviewers + - uses: actions/github-script@v7 + with: + script: | + const { owner, repo, number } = context.issue; + const pr = await github.rest.pulls.get({ owner, repo, pull_number: number }); + + // Require 2 reviews from code owners + if (pr.data.review_comments < 2) { + core.setFailed('Requires at least 2 review comments'); + } + + # Enforce test coverage minimum + - uses: actions/setup-node@v3 + with: + node-version: 18 + cache: npm + + - run: npm ci + - run: npm run test:coverage + + - name: Check coverage thresholds + run: | + COVERAGE=$(cat coverage/coverage-summary.json | jq '.total.lines.pct') + if (( $(echo "$COVERAGE < 85" | bc -l) )); then + echo "❌ Test coverage $COVERAGE% is below 85% threshold" + exit 1 + fi + echo "✓ Test coverage $COVERAGE% meets threshold" +``` + +--- + +### 5. Deploying Directly from Personal Laptops + +**Anti-Pattern:** +``` +❌ "I'll deploy from my machine" +❌ Manual SSH to production servers +❌ No audit trail +❌ Different versions deployed +❌ Developers have production access +``` + +**Problem:** +- No reproducibility +- No rollback capability +- Security vulnerabilities +- Compliance violations +- Knowledge not shared + +**Solution:** + +```yaml +# Enforce deployment only through automated pipelines +name: Production Deployment + +on: + workflow_dispatch: + inputs: + version: + description: 'Version to deploy' + required: true + +jobs: + deploy: + environment: + name: production + url: https://api.acme.com + runs-on: ubuntu-latest + permissions: + id-token: write # For OIDC + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.inputs.version }} + + - name: Verify version exists and is tagged + run: | + git describe --exact-match --tags ${{ github.event.inputs.version }} || exit 1 + + - name: Authenticate to production + uses: aws-actions/configure-aws-credentials@v2 + with: + role-to-assume: ${{ secrets.PROD_ROLE_ARN }} + role-session-name: github-actions-deploy + + - name: Deploy with rollback capability + run: | + ./scripts/deploy.sh \ + --version ${{ github.event.inputs.version }} \ + --enable-rollback \ + --verify-health \ + --canary 10 + + # GitHub Actions provides: + # ✓ Authentication (OIDC, no keys) + # ✓ Audit trail (Who, When, What) + # ✓ Approval gates (environment protection) + # ✓ Reproducibility (exact version) +``` + +--- + +### 6. Insufficient Monitoring and Alerting + +**Anti-Pattern:** +``` +❌ No dashboard for CI/CD health +❌ Build failures go unnoticed +❌ Security alerts ignored +❌ Performance degradation undetected +❌ Cost overruns unexpected +``` + +**Problem:** +- Issues discovered by users +- Slow incident response +- Unknown cost drivers +- Blind spots in security + +**Solution:** + +```yaml +# .github/workflows/publish-metrics.yml +name: Publish Platform Metrics + +on: + schedule: + - cron: '*/5 * * * *' # Every 5 minutes + +jobs: + collect-metrics: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Collect workflow metrics + uses: actions/github-script@v7 + env: + PROMETHEUS_PUSHGATEWAY: ${{ secrets.PROMETHEUS_PUSHGATEWAY }} + with: + script: | + const axios = require('axios'); + + // Get workflow run times + const runs = await github.rest.actions.listWorkflowRuns({ + owner: context.repo.owner, + repo: context.repo.repo, + per_page: 100 + }); + + const metrics = { + 'workflow_duration_minutes': [], + 'workflow_failures': 0, + 'workflow_successes': 0 + }; + + for (const run of runs.data.workflow_runs) { + if (run.status === 'completed') { + const duration = new Date(run.updated_at) - new Date(run.created_at); + metrics.workflow_duration_minutes.push(duration / 60000); + + if (run.conclusion === 'success') { + metrics.workflow_successes++; + } else { + metrics.workflow_failures++; + } + } + } + + // Push to monitoring + await axios.post( + process.env.PROMETHEUS_PUSHGATEWAY, + formatMetrics(metrics) + ); +``` + +--- + +### 7. Granting Excessive Permissions + +**Anti-Pattern:** +``` +❌ Everyone has admin access +❌ No role-based access control +❌ Contractors have production access +❌ GitHub tokens never rotate +❌ Machine accounts have user permissions +``` + +**Problem:** +- Increased attack surface +- Accidental deletions/changes +- Compliance violations +- Impossible to audit who did what + +**Solution:** + +```yaml +# Principle of Least Privilege +organizations: + acme-platform: + custom_roles: + - name: junior_developer + permissions: + - pull_requests: write + - issues: write + - packages: read + # ✓ Cannot delete repos, modify settings, merge to main + + - name: senior_developer + permissions: + - pull_requests: write + - issues: write + - packages: read + - workflows: write + - repository_hooks: write + + - name: devops_engineer + permissions: + - admin: true + # Scoped to infrastructure repos only + + - name: security_reviewer + permissions: + - pull_requests: read + - security_events: read + - settings: read + +# Use environment-based deployment restrictions +environments: + production: + protection_rules: + - required_reviewers: + minimum_count: 2 + # Only senior devs and devops can approve + teams: [senior-developers, devops-engineers] + - custom_deployment_rules: + - type: required_status_checks + contexts: [security-scan, integration-tests] + +# Use GitHub Apps for fine-grained permissions +github_apps: + - name: deployment-bot + permissions: + deployments: write + contents: read + pull_requests: read + # ✓ Cannot delete, modify settings, or access user data +``` + +--- + +### 8. No Documentation or Knowledge Sharing + +**Anti-Pattern:** +``` +❌ Knowledge only in individuals' heads +❌ No runbooks for common tasks +❌ "How does X work?" - "Only Bob knows" +❌ Onboarding takes weeks +❌ When someone leaves, context is lost +``` + +**Problem:** +- Onboarding delays +- Inconsistent procedures +- Knowledge silos +- Bus factor = 1 +- Operational inefficiency + +**Solution:** + +```markdown +# Example: docs/runbooks/incident-response.md + +## Incident Response Runbook + +### Severity Levels +- **P1 (Critical):** Complete outage, customer impact +- **P2 (High):** Partial outage, degraded performance +- **P3 (Medium):** Minor issues, workarounds available +- **P4 (Low):** No customer impact + +### Response Steps + +#### Step 1: Acknowledge (Immediately) +```bash +# Acknowledge in Slack +@incident-commander acknowledged incident in #incidents +``` + +#### Step 2: Gather Information (2 min) +- [ ] Access monitoring dashboard (Grafana) +- [ ] Check recent deployments +- [ ] Review error rates and latency +- [ ] Check infrastructure status + +#### Step 3: Execute Runbook +Based on error pattern, execute appropriate runbook: +- [Database replication lag](./db-replication-lag.md) +- [High error rate](./high-error-rate.md) +- [Deployment rollback](./deployment-rollback.md) + +#### Step 4: Communicate Status +```bash +# Update status every 5 minutes +gh issue comment --body "Status: Still investigating..." +``` + +#### Step 5: Post-Incident +- [ ] Complete post-mortem within 24 hours +- [ ] Create follow-up GitHub issues +- [ ] Update runbooks based on learnings +- [ ] Share learnings with team +``` + +--- + +### 9. Overlooking Environment Configuration Drift + +**Anti-Pattern:** +``` +❌ Environments configured manually +❌ "Apply this change to production" via email +❌ No version control for infrastructure +❌ Can't replicate prod locally +❌ Settings lost when servers are replaced +``` + +**Problem:** +- Environments diverge over time +- Difficult to debug "works in prod but not staging" +- Disaster recovery nearly impossible +- Compliance audit failures + +**Solution:** + +```hcl +# Terraform: Infrastructure as Code +terraform { + required_providers { + github = { + source = "integrations/github" + version = "~> 6.0" + } + } + + backend "s3" { + bucket = "terraform-state" + key = "github/main.tfstate" + encrypt = true + dynamodb_table = "terraform-locks" + } +} + +# Define all environments from code +module "dev_environment" { + source = "./modules/github-org" + + org_name = "acme-dev" + visibility = "internal" + + required_status_checks = ["ci", "lint"] + required_reviewers = 1 +} + +module "prod_environment" { + source = "./modules/github-org" + + org_name = "acme-prod" + visibility = "private" + + required_status_checks = ["ci", "lint", "security-scan", "performance-test"] + required_reviewers = 2 + require_code_owners = true +} + +# Version control all changes +# git log shows who changed what and when +``` + +--- + +### 10. Ignoring Cost Management + +**Anti-Pattern:** +``` +❌ "GitHub is cheap, don't worry about costs" +❌ No Actions minute limits +❌ No artifact retention policy +❌ GitHub Copilot seats assigned but unused +❌ Large repositories not optimized +``` + +**Problem:** +- Costs spiral unchecked +- Wasted spending +- Business can't predict budgets +- No ROI analysis + +**Solution:** + +```python +# Cost monitoring and optimization +import boto3 +import json +from datetime import datetime, timedelta + +class GitHubCostOptimizer: + def __init__(self, github_token, org_name): + self.github_token = github_token + self.org_name = org_name + self.gh = GitHubAPI(github_token) + + def analyze_actions_usage(self): + """Analyze GitHub Actions minute consumption""" + usage = self.gh.get_organization_actions_usage(self.org_name) + + # Find top consumers + repo_usage = {} + for repo in usage.get('repositories', []): + minutes = repo['actions_minutes_used'] + repo_usage[repo['name']] = minutes + + top_10 = sorted(repo_usage.items(), key=lambda x: x[1], reverse=True)[:10] + + print("Top 10 Actions consumers:") + for repo, minutes in top_10: + print(f" {repo}: {minutes} minutes (${minutes * 0.008})") + + return top_10 + + def optimize_expensive_workflows(self): + """Identify and optimize expensive workflows""" + improvements = [] + + for repo in self.gh.list_repositories(self.org_name): + workflows = self.gh.get_workflows(repo) + + for workflow in workflows: + runs = self.gh.get_workflow_runs(workflow, limit=10) + + for run in runs: + # Check for optimization opportunities + if self.could_use_caching(run): + improvements.append({ + 'repo': repo, + 'workflow': workflow['name'], + 'suggestion': 'Enable dependency caching', + 'potential_savings': '40%' + }) + + if self.has_sequential_jobs(run): + improvements.append({ + 'repo': repo, + 'workflow': workflow['name'], + 'suggestion': 'Parallelize jobs', + 'potential_savings': '30%' + }) + + return improvements + + def optimize_runners(self): + """Right-size runner usage""" + # Analyze runner utilization + # Recommend spot instances for non-critical workloads + # Suggest self-hosted runners for high-volume workloads + pass + + def cleanup_artifacts(self): + """Remove old/unused artifacts""" + for repo in self.gh.list_repositories(self.org_name): + artifacts = self.gh.get_artifacts(repo) + + # Keep only recent artifacts + cutoff = datetime.now() - timedelta(days=30) + + for artifact in artifacts: + if artifact['created_at'] < cutoff: + self.gh.delete_artifact(artifact['id']) + print(f"✓ Deleted old artifact: {artifact['name']}") +``` + +**Cross-reference:** See the Pillars section on Cost Optimization for detailed strategies. + + +## Key Performance Indicators (KPIs) + +Measuring GitHub platform effectiveness through carefully selected KPIs enables data-driven optimization and demonstrates business value. + +### Development Velocity Metrics + +| KPI | Target | Frequency | Tool | +|-----|--------|-----------|------| +| **Deployment Frequency** | 10-20x/day | Daily | GitHub API | +| **Lead Time for Changes** | < 1 hour | Weekly | GitHub API | +| **Mean Time to Recovery (MTTR)** | < 30 min | Per incident | Incident tracking | +| **Change Failure Rate** | < 15% | Weekly | Deployment logs | +| **Cycle Time** | < 2 days | Weekly | GitHub Projects | + +**Implementation:** + +```python +# Calculate velocity metrics +from datetime import datetime, timedelta +import statistics + +class VelocityMetrics: + def __init__(self, gh_api): + self.gh = gh_api + + def deployment_frequency(self, org, days=30): + """Deployments per day""" + deployments = self.gh.get_deployments(org, days) + + days_with_deployments = len(set( + d['created_at'].date() for d in deployments + )) + + total_days = min(days, (datetime.now() - datetime.now() - timedelta(days=days)).days) + + return { + 'deployments_per_day': len(deployments) / total_days, + 'days_with_deployments': days_with_deployments, + 'total_deployments': len(deployments) + } + + def lead_time_for_changes(self, org, repos=None): + """Time from commit to production""" + if not repos: + repos = self.gh.list_repositories(org) + + lead_times = [] + + for repo in repos: + pulls = self.gh.get_merged_pulls(repo, days=30) + + for pr in pulls: + # Time from PR creation to merge + created = datetime.fromisoformat(pr['created_at']) + merged = datetime.fromisoformat(pr['merged_at']) + lead_time = (merged - created).total_seconds() / 3600 # hours + lead_times.append(lead_time) + + return { + 'mean_hours': statistics.mean(lead_times), + 'median_hours': statistics.median(lead_times), + 'p95_hours': np.percentile(lead_times, 95), + 'p99_hours': np.percentile(lead_times, 99) + } + + def change_failure_rate(self, org, days=30): + """Percentage of deployments causing incidents""" + deployments = self.gh.get_deployments(org, days) + failed_deployments = self.gh.get_failed_deployments(org, days) + + if not deployments: + return 0 + + return (len(failed_deployments) / len(deployments)) * 100 +``` + +### Code Quality Metrics + +| KPI | Target | Frequency | Tool | +|-----|--------|-----------|------| +| **Test Coverage** | > 85% | Per PR | CodeCov/Codecov | +| **Security Findings** | 0 critical/high | Daily | GitHub GHAS | +| **Code Review Cycle Time** | < 4 hours | Weekly | GitHub API | +| **Merge Conflict Rate** | < 5% | Weekly | GitHub API | +| **Code Churn** | < 20% | Weekly | Git analytics | + +**Dashboard Query:** + +```sql +-- Calculate code quality metrics +SELECT + repository, + COUNT(CASE WHEN security_severity = 'critical' THEN 1 END) as critical_findings, + COUNT(CASE WHEN security_severity = 'high' THEN 1 END) as high_findings, + AVG(test_coverage) as avg_coverage, + AVG(review_time_hours) as avg_review_time +FROM code_quality_metrics +WHERE date >= NOW() - INTERVAL '7 days' +GROUP BY repository +ORDER BY critical_findings DESC; +``` + +### Operational Excellence Metrics + +| KPI | Target | Frequency | Tool | +|-----|--------|-----------|------| +| **Build Success Rate** | > 95% | Daily | GitHub Actions | +| **Build Duration** | < 20 min | Daily | GitHub Actions | +| **Repository Coverage** | 100% | Monthly | GitHub API | +| **Policy Compliance** | 100% | Weekly | Compliance tool | +| **Incident Response Time** | < 15 min | Per incident | Incident tracking | + +**Calculation Example:** + +```python +def build_success_rate(org, days=7): + """% of successful workflow runs""" + runs = github.get_workflow_runs(org, days) + + successful = len([r for r in runs if r['conclusion'] == 'success']) + total = len(runs) + + return { + 'success_rate': (successful / total * 100) if total > 0 else 0, + 'total_runs': total, + 'successful_runs': successful, + 'failed_runs': total - successful + } +``` + +### Security and Compliance Metrics + +| KPI | Target | Frequency | Tool | +|-----|--------|-----------|------| +| **Dependency Vulnerabilities** | 0 critical | Daily | Dependabot | +| **Secret Exposure Incidents** | 0 | Real-time | Secret scanning | +| **Unreviewed Code** | 0% | Daily | GitHub API | +| **Access Control Violations** | 0 | Daily | Audit logs | +| **Compliance Violations** | 0 | Weekly | Compliance tool | + +**Monitoring Dashboard:** + +```yaml +# Prometheus metrics exposed by custom exporter +github_vulnerabilities_critical: 0 +github_vulnerabilities_high: 2 +github_secrets_exposed: 0 +github_audit_log_events: 1542 +github_access_violations: 0 +github_branch_protection_violations: 1 +github_policy_violations: 3 +``` + +### Team and Organization Metrics + +| KPI | Target | Frequency | Tool | +|-----|--------|-----------|------| +| **Onboarding Time** | < 3 days | Per new member | Manual tracking | +| **Developer Satisfaction** | > 4.0/5.0 | Quarterly | Survey | +| **Knowledge Distribution** | Gini < 0.3 | Monthly | Code ownership | +| **Team Autonomy** | > 70% self-service | Monthly | GitHub API | +| **Community Contribution** | > 20% external | Monthly | GitHub API | + +### Cost Metrics + +| KPI | Target | Frequency | Tool | +|-----|--------|-----------|------| +| **Cost per Developer** | $500-$1000/year | Monthly | Billing API | +| **Cost per Deployment** | < $5 | Per deployment | Cost analysis | +| **Actions Minutes Efficiency** | < 3 min/deployment | Daily | GitHub API | +| **Storage Cost** | < $100/month | Monthly | Billing API | +| **Copilot ROI** | > 3:1 | Quarterly | Usage analysis | + +**Cost Tracking Script:** + +```python +class CostTracker: + def monthly_cost_analysis(self, org): + """Detailed cost breakdown by category""" + billing = self.gh.get_billing_info(org) + + costs = { + 'github_pro_seats': billing['pro_users'] * 4, # $4/user/month + 'actions_minutes': billing['actions_minutes_used'] * 0.008, + 'packages_storage': billing['packages_gb_used'] * 0.25, + 'actions_storage': billing['actions_storage_gb'] * 0.25, + 'advanced_security': billing['ghas_repos'] * 3, + 'copilot_seats': billing['copilot_seats'] * 10, + } + + total = sum(costs.values()) + + return { + 'costs': costs, + 'total': total, + 'cost_per_dev': total / billing['total_users'], + 'breakdown': {k: v/total*100 for k, v in costs.items()} + } +``` + +### KPI Dashboard Configuration + +```yaml +# Grafana dashboard configuration +dashboard: + title: GitHub Enterprise Platform KPIs + panels: + - title: Deployment Frequency + query: rate(deployments_total[1d]) + target: 10-20 + threshold_warning: 5 + threshold_critical: 2 + + - title: Mean Lead Time + query: histogram_quantile(0.5, lead_time_hours) + target: 1 + threshold_warning: 4 + threshold_critical: 8 + + - title: Security Findings + query: count(security_findings{severity="critical"}) + target: 0 + threshold_warning: 1 + threshold_critical: 5 + + - title: Build Success Rate + query: rate(workflow_success[1d]) / rate(workflow_total[1d]) + target: 0.95 + threshold_warning: 0.90 + threshold_critical: 0.80 + + - title: Monthly Cost + query: github_monthly_cost + target: null + threshold_warning: null + threshold_critical: null +``` + +--- + +## Implementation Roadmap + +### Timeline Overview + +``` +Phase 1: Foundation Phase 2: Standardization Phase 3: Optimization +(Weeks 1-4) (Weeks 5-12) (Weeks 13-26) +├─ Setup ├─ Policy Enforcement ├─ Advanced Automation +├─ Security Baseline ├─ CI/CD Automation ├─ Governance Automation +├─ Identity ├─ Knowledge Transfer ├─ Cost Optimization +└─ Initial Org └─ Process Definition └─ Platform Maturity +``` + +### Detailed Phase Timeline + +**Phase 1: Foundation (Weeks 1-4)** + +| Week | Activities | Deliverables | +|------|-----------|--------------| +| 1 | Enterprise account setup, SAML SSO, initial policies | GitHub Enterprise account, SSO working, initial org | +| 2 | Team structure, basic security scanning, audit logging | Teams created, security scanning enabled, logs flowing | +| 3 | Repository templates, branch protection, access control | Templates available, branch protection enforced | +| 4 | Initial CI/CD setup, basic monitoring | GitHub Actions working, basic dashboard | + +**Phase 2: Standardization (Weeks 5-12)** + +| Week | Activities | Deliverables | +|------|-----------|--------------| +| 5-6 | Repository governance policy, naming enforcement | Policy document, template enforcement | +| 7-8 | Advanced CI/CD patterns, multi-environment deployments | Deployment pipelines, environment configs | +| 9-10 | Knowledge base and runbooks, team training | Documentation, training completed | +| 11-12 | Change management process, approval workflows | Process documented, workflows configured | + +**Phase 3: Optimization (Weeks 13-26)** + +| Week | Activities | Deliverables | +|------|-----------|--------------| +| 13-14 | Advanced security automation, policy enforcement | Security automation, policies enforced | +| 15-16 | Cost optimization, usage monitoring | Cost dashboards, optimization strategies | +| 17-18 | Performance optimization, scaling patterns | Optimized workflows, scaling ready | +| 19-20 | AI/ML integration, advanced analytics | Analytics dashboards, ML models | +| 21-24 | Disaster recovery, backup procedures, testing | DR plan documented, tested | +| 25-26 | Maturity assessment, improvement plan | Assessment complete, continuous improvement | + +### Detailed Action Items + +**Week 1 Activities:** + +```yaml +GitHub Enterprise Setup: + - Create GitHub Enterprise Cloud account + - Configure enterprise settings + - Set up billing and payment method + - Configure enterprise-level IP allow list + - Enable audit log streaming + +SAML SSO Configuration: + - Integrate with corporate IdP (Okta/Azure AD) + - Configure SCIM provisioning + - Test SSO login + - Enable MFA requirement + +Initial Organization: + - Create main organization + - Configure base permissions + - Create owner and billing manager roles + - Set default repository permissions +``` + +**Week 2-3 Activities:** + +```yaml +Security & Access: + - Enable GitHub Advanced Security + - Configure secret scanning with custom patterns + - Enable push protection for secrets + - Set up audit log SIEM integration + - Configure security advisories + +Teams and Permissions: + - Define team hierarchy + - Create cross-functional teams + - Configure team maintainers + - Set up team synchronization + - Create custom organization roles + +Repository Standards: + - Create repository templates (microservice, frontend, lib) + - Add standard files (README, CONTRIBUTING, LICENSE) + - Pre-configure branch protection rules + - Add issue and PR templates + - Include standard GitHub Actions workflows +``` + +### Resource Requirements + +```yaml +Team Structure: + GitHub Architects: 1-2 FTE + - Enterprise design + - Policy development + - Security strategy + + DevOps Engineers: 2-3 FTE + - CI/CD pipeline development + - Infrastructure automation + - Monitoring and observability + + Security Engineers: 1-2 FTE + - Security scanning setup + - Access control implementation + - Compliance verification + + Platform Engineers: 2-4 FTE + - Developer experience + - Self-service tooling + - Documentation + +Tools and Infrastructure: + - GitHub Enterprise Cloud license ($231k-$500k/year for 1000 seats) + - Self-hosted runners infrastructure (if needed) + - SIEM integration (Splunk, Datadog, etc.) + - Monitoring and observability (Prometheus, Grafana) + - Secret management (HashiCorp Vault, AWS Secrets Manager) + - Infrastructure automation (Terraform, Ansible) +``` + +### Success Criteria + +**Phase 1 Success:** +- ✓ All developers using GitHub with SSO +- ✓ Basic security scanning enabled on 100% of repositories +- ✓ Audit logging active and centralized +- ✓ Team adoption > 80% + +**Phase 2 Success:** +- ✓ 100% of repositories use naming conventions +- ✓ CI/CD pipelines automated for 100% of services +- ✓ Change management process in use +- ✓ 90% team adoption, regular feedback + +**Phase 3 Success:** +- ✓ Security and cost automated +- ✓ 95%+ deployment success rate +- ✓ MTTR < 30 minutes +- ✓ Platform self-serve capability +- ✓ Continuous innovation cycle established + +--- + +## References + +### GitHub Documentation + +- [GitHub Enterprise Cloud Documentation](https://docs.github.com/en/enterprise-cloud@latest) +- [GitHub Advanced Security Documentation](https://docs.github.com/en/code-security/secret-scanning) +- [GitHub Actions Documentation](https://docs.github.com/en/actions) +- [GitHub REST API](https://docs.github.com/en/rest) +- [GitHub GraphQL API](https://docs.github.com/en/graphql) + +### Industry Standards and Frameworks + +- [DORA Metrics](https://dora.dev/) - DevOps Research and Assessment +- [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) +- [Microsoft Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/architecture/framework/) +- [GitOps Best Practices](https://opengitops.dev/) +- [Trunk-Based Development](https://trunkbaseddevelopment.com/) + +### Security and Compliance + +- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework/) +- [CIS Controls](https://www.cisecurity.org/controls/) +- [OWASP Top 10](https://owasp.org/Top10/) +- [GitHub Security Best Practices](https://docs.github.com/en/code-security) + +### Tools and Integration + +- [GitHub CLI](https://cli.github.com/) - Official GitHub command-line tool +- [Terraform GitHub Provider](https://registry.terraform.io/providers/integrations/github/latest/docs) +- [GitHub Actions Marketplace](https://github.com/marketplace) +- [Dependabot](https://docs.github.com/en/code-security/dependabot) + +### Related Documentation in This Series + +1. [Enterprise Hierarchy Design](01-enterprise-hierarchy.md) +2. [Organization Strategies](02-organization-strategies.md) +3. [Identity and Access Management](03-identity-access-management.md) +4. [Enterprise Managed Users](04-enterprise-managed-users.md) +5. [Teams and Permissions](05-teams-permissions.md) +6. [Policy Inheritance](06-policy-inheritance.md) +7. [Repository Governance](07-repository-governance.md) +8. [Security and Compliance](08-security-compliance.md) + +### Recommended Reading + +- **The Phoenix Project** by Gene Kim - Understanding DevOps transformation +- **Accelerate** by Nicole Forsgren et al. - Measuring software development performance +- **Site Reliability Engineering** by Betsy Beyer et al. - Operations best practices +- **The Twelve-Factor App** by Adam Wiggins - Application design principles +- **Building Microservices** by Sam Newman - Architecture patterns + +### External Resources + +- [GitHub Enterprise Blog](https://github.blog/enterprise/) +- [GitHub Community Forum](https://github.community/) +- [GitHub Education](https://education.github.com/) +- [GitHub Skills](https://skills.github.com/) +- [O'Reilly Learning Platform](https://learning.oreilly.com/) - Courses on Git and DevOps + +### Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | 2024 | Initial comprehensive WAF documentation | + +--- + +## Appendix: Configuration Templates + +### Enterprise-Level Rulesets (JSON) + +```json +{ + "name": "Enterprise Core Rules", + "target": "branch", + "bypass_actors": [ + { + "actor_type": "Organization", + "actor_id": null, + "bypass_mode": "always" + } + ], + "enforcement": "active", + "conditions": { + "ref_name": { + "include": ["refs/heads/main", "refs/heads/develop"], + "exclude": [] + } + }, + "rules": [ + { + "type": "pull_request", + "parameters": { + "required_approving_review_count": 2, + "require_code_owner_review": true, + "require_last_push_approval": true, + "dismiss_stale_reviews_on_push": false + } + }, + { + "type": "required_status_checks", + "parameters": { + "strict_required_status_checks_policy": true, + "required_status_checks": [ + { + "context": "Security / CodeQL Analysis", + "integration_id": null + }, + { + "context": "Test / Unit Tests", + "integration_id": null + } + ] + } + }, + { + "type": "committed_signatures", + "parameters": {} + }, + { + "type": "non_fast_forward", + "parameters": {} + } + ] +} +``` + +### GitHub Actions Reusable Workflow + +```yaml +# .github/workflows/shared-security-scan.yml +name: Security Scan (Reusable) + +on: + workflow_call: + inputs: + scan-type: + description: 'Type of security scan' + required: true + type: string + default: 'full' + +jobs: + security-scan: + runs-on: ubuntu-latest + permissions: + security-events: write + contents: read + pull-requests: write + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run CodeQL + if: inputs.scan-type == 'full' || inputs.scan-type == 'codeql' + uses: github/codeql-action/init@v2 + + - name: Run Secret Scanning + uses: trufflesecurity/trufflehog@main + with: + path: ./ + base: ${{ github.event.repository.default_branch }} + head: HEAD + + - name: Upload results + uses: github/codeql-action/upload-sarif@v2 + with: + sarif_file: 'results.sarif' +``` + +--- + +**Document Complete** + +This comprehensive GitHub Well-Architected Framework document provides enterprise-grade guidance for implementing GitHub at scale. Organizations should use this as a reference for designing, implementing, and optimizing their GitHub infrastructure. + +For questions or updates, refer to the related documentation series or contact your GitHub Enterprise Account Team. + diff --git a/docs/10-reference-architecture.md b/docs/10-reference-architecture.md new file mode 100644 index 0000000..091d554 --- /dev/null +++ b/docs/10-reference-architecture.md @@ -0,0 +1,1014 @@ +# Reference Architecture + +> **Consolidated architecture diagrams, reference patterns, and quick reference guides for GitHub Enterprise Cloud administration and governance.** + +--- + +## Table of Contents + +- [Complete Enterprise Architecture](#complete-enterprise-architecture) +- [Organization Topology Patterns](#organization-topology-patterns) +- [IAM Integration Architecture](#iam-integration-architecture) +- [Security Scanning Architecture](#security-scanning-architecture) +- [CI/CD Pipeline Governance Architecture](#cicd-pipeline-governance-architecture) +- [Hybrid and Multi-Cloud Integration](#hybrid-and-multi-cloud-integration) +- [Migration Architecture](#migration-architecture) +- [Quick Reference Cards](#quick-reference-cards) + +--- + +## Complete Enterprise Architecture + +The complete GitHub Enterprise Cloud architecture shows all major components and their relationships. + +```mermaid +graph TB + subgraph "Identity Provider" + IdP[Identity Provider
Entra ID / Okta] + IdPGroups[IdP Groups] + end + + subgraph "GitHub Enterprise Cloud" + Enterprise[Enterprise Account] + + subgraph "Organizations" + OrgProd[Production Org] + OrgDev[Development Org] + OrgSandbox[Sandbox Org] + end + + subgraph "IAM Layer" + SAML[SAML SSO] + SCIM[SCIM Provisioning] + EMU[Enterprise Managed Users] + end + + subgraph "Security Layer" + GHAS[GitHub Advanced Security] + CodeQL[Code Scanning] + SecretScan[Secret Scanning] + Dependabot[Dependabot] + end + + subgraph "Governance Layer" + Policies[Enterprise Policies] + Rulesets[Repository Rulesets] + Audit[Audit Logs] + end + end + + subgraph "External Integrations" + SIEM[SIEM System] + Backup[Backup Solution] + CICD[CI/CD Platform] + end + + IdP -->|SAML Auth| SAML + IdP -->|SCIM Sync| SCIM + SCIM -->|Provision| EMU + IdPGroups -->|Team Sync| OrgProd + IdPGroups -->|Team Sync| OrgDev + + Enterprise --> Policies + Policies --> OrgProd + Policies --> OrgDev + Policies --> OrgSandbox + + OrgProd --> GHAS + OrgDev --> GHAS + GHAS --> CodeQL + GHAS --> SecretScan + GHAS --> Dependabot + + Policies --> Rulesets + Rulesets --> OrgProd + Rulesets --> OrgDev + + Audit -->|Stream| SIEM + OrgProd -->|Backup| Backup + OrgProd -->|Workflows| CICD + + style Enterprise fill:#0366d6,color:#fff + style GHAS fill:#28a745,color:#fff + style Policies fill:#6f42c1,color:#fff +``` + +### Architecture Components + +1. **Identity Provider Layer**: Centralized authentication and user provisioning +2. **IAM Layer**: SAML SSO, SCIM provisioning, and Enterprise Managed Users +3. **Organization Layer**: Multi-org topology for environment separation +4. **Security Layer**: GitHub Advanced Security features +5. **Governance Layer**: Enterprise policies, rulesets, and audit logging +6. **Integration Layer**: External systems (SIEM, backup, CI/CD) + +--- + +## Organization Topology Patterns + +### Pattern 1: Single Organization + +```mermaid +graph TB + Enterprise[Enterprise Account] + + subgraph "Single Organization" + Org[acme-corp] + + subgraph "Teams by Function" + Platform[Platform Team] + Frontend[Frontend Team] + Backend[Backend Team] + Security[Security Team] + end + + subgraph "Repositories" + ProdRepos[Production Repos] + DevRepos[Development Repos] + InfraRepos[Infrastructure Repos] + end + end + + Enterprise --> Org + Org --> Platform + Org --> Frontend + Org --> Backend + Org --> Security + + Platform --> InfraRepos + Frontend --> ProdRepos + Backend --> ProdRepos + Security --> ProdRepos + + style Enterprise fill:#0366d6,color:#fff + style Org fill:#28a745,color:#fff +``` + +**Best For:** +- Small to medium enterprises (< 500 developers) +- Single business unit +- Unified governance model +- Simple compliance requirements + +### Pattern 2: Multi-Organization (Red-Green-Sandbox-Archive) + +```mermaid +graph TB + Enterprise[Enterprise Account] + + subgraph "Production Environment" + Red[acme-prod-red] + Green[acme-prod-green] + end + + subgraph "Non-Production" + Dev[acme-dev] + Sandbox[acme-sandbox] + end + + subgraph "Historical" + Archive[acme-archive] + end + + Enterprise --> Red + Enterprise --> Green + Enterprise --> Dev + Enterprise --> Sandbox + Enterprise --> Archive + + Red -.->|Blue-Green Deploy| Green + Dev -->|Promote| Red + Sandbox -.->|Experiment| Dev + Red -.->|Retire| Archive + + style Enterprise fill:#0366d6,color:#fff + style Red fill:#dc3545,color:#fff + style Green fill:#28a745,color:#fff + style Dev fill:#ffc107,color:#000 + style Sandbox fill:#17a2b8,color:#fff + style Archive fill:#6c757d,color:#fff +``` + +**Best For:** +- Large enterprises (500+ developers) +- Blue-green deployment patterns +- Multiple environments with strict separation +- Complex compliance requirements +- Innovation and experimentation needs + +### Pattern 3: Business Unit Separation + +```mermaid +graph TB + Enterprise[Enterprise Account] + + subgraph "Business Units" + BU1[acme-retail] + BU2[acme-wholesale] + BU3[acme-logistics] + end + + subgraph "Shared Services" + Platform[acme-platform] + Security[acme-security] + end + + Enterprise --> BU1 + Enterprise --> BU2 + Enterprise --> BU3 + Enterprise --> Platform + Enterprise --> Security + + Platform -.->|Shared Libraries| BU1 + Platform -.->|Shared Libraries| BU2 + Platform -.->|Shared Libraries| BU3 + + Security -.->|Security Scanning| BU1 + Security -.->|Security Scanning| BU2 + Security -.->|Security Scanning| BU3 + + style Enterprise fill:#0366d6,color:#fff + style BU1 fill:#28a745,color:#fff + style BU2 fill:#28a745,color:#fff + style BU3 fill:#28a745,color:#fff + style Platform fill:#6f42c1,color:#fff + style Security fill:#dc3545,color:#fff +``` + +**Best For:** +- Multi-division enterprises +- Independent P&L units +- Different compliance requirements per unit +- Decentralized governance + +--- + +## IAM Integration Architecture + +### Enterprise Managed Users (EMU) with Microsoft Entra ID + +```mermaid +sequenceDiagram + participant User + participant EntraID as Microsoft Entra ID + participant SCIM as SCIM Endpoint + participant GitHub as GitHub Enterprise + participant Repo as Repository + + Note over EntraID,GitHub: Initial Provisioning + EntraID->>SCIM: Create User (SCIM 2.0) + SCIM->>GitHub: Provision username_shortcode + GitHub-->>SCIM: User Created + SCIM-->>EntraID: Confirmation + + Note over EntraID,GitHub: Group Synchronization + EntraID->>SCIM: Sync Group Membership + SCIM->>GitHub: Update Team Membership + GitHub-->>SCIM: Team Updated + + Note over User,Repo: Authentication Flow + User->>EntraID: Login Request + EntraID->>User: MFA Challenge + User->>EntraID: MFA Token + EntraID->>GitHub: SAML Assertion + GitHub->>User: Session Token + User->>Repo: Access Repository + Repo->>GitHub: Verify Permissions + GitHub-->>Repo: Access Granted + Repo-->>User: Repository Content + + Note over EntraID,GitHub: Deprovisioning + EntraID->>SCIM: Delete User + SCIM->>GitHub: Suspend Account + GitHub-->>SCIM: Account Suspended +``` + +### Personal Accounts with SAML SSO + +```mermaid +graph LR + subgraph "Identity Provider" + IdP[Okta / Entra ID] + end + + subgraph "GitHub Enterprise" + Enterprise[Enterprise Account] + Org1[Organization 1] + Org2[Organization 2] + end + + subgraph "Users" + PersonalAcct[Personal GitHub Account] + end + + IdP -->|SAML SSO| Enterprise + Enterprise --> Org1 + Enterprise --> Org2 + PersonalAcct -->|SSO Required| Org1 + PersonalAcct -->|SSO Required| Org2 + IdP -.->|Authenticate| PersonalAcct + + style IdP fill:#0366d6,color:#fff + style Enterprise fill:#28a745,color:#fff + style PersonalAcct fill:#ffc107,color:#000 +``` + +**Key Differences:** + +| Feature | EMU | Personal Accounts with SSO | +|---------|-----|---------------------------| +| Identity Source | IdP only | GitHub + IdP | +| Username Format | user_shortcode | user (personal) | +| Account Creation | IdP provisioning | Self-service | +| Deprovisioning | Automatic via SCIM | Manual removal | +| External Collaboration | Limited | Full access | +| Public Repos | Enterprise only | Personal + Enterprise | + +--- + +## Security Scanning Architecture + +### GitHub Advanced Security Pipeline + +```mermaid +graph TB + subgraph "Developer Workflow" + Dev[Developer] + LocalCode[Local Code] + Commit[Git Commit] + end + + subgraph "GitHub Repository" + PR[Pull Request] + MainBranch[Main Branch] + end + + subgraph "Security Scanning" + SecretScan[Secret Scanning
Push Protection] + CodeQL[CodeQL Analysis] + DependencyReview[Dependency Review] + Dependabot[Dependabot Alerts] + end + + subgraph "Security Dashboard" + Alerts[Security Alerts] + Dashboard[Security Overview] + Reports[Compliance Reports] + end + + Dev --> LocalCode + LocalCode --> Commit + Commit -->|Push| SecretScan + SecretScan -->|Block if Secret Found| Commit + SecretScan -->|Pass| PR + + PR --> CodeQL + PR --> DependencyReview + + CodeQL -->|Vulnerabilities| Alerts + DependencyReview -->|CVEs| Alerts + Dependabot -->|Updates| PR + + MainBranch --> Dependabot + MainBranch --> CodeQL + + Alerts --> Dashboard + Dashboard --> Reports + + style SecretScan fill:#dc3545,color:#fff + style CodeQL fill:#28a745,color:#fff + style DependencyReview fill:#ffc107,color:#000 + style Alerts fill:#dc3545,color:#fff +``` + +### Secret Scanning with Push Protection + +```mermaid +sequenceDiagram + participant Dev as Developer + participant Git as Git Client + participant GitHub as GitHub + participant SecretScan as Secret Scanner + participant Security as Security Team + + Dev->>Git: git push + Git->>GitHub: Push commits + GitHub->>SecretScan: Scan commits + + alt Secret Detected + SecretScan-->>GitHub: Secret Found + GitHub-->>Git: Push Blocked + Git-->>Dev: Error: Secret detected + Dev->>GitHub: Request bypass (with justification) + GitHub->>Security: Bypass request notification + Security->>GitHub: Approve/Deny + + alt Approved + GitHub-->>Dev: Bypass granted + Dev->>Git: git push (with bypass token) + Git->>GitHub: Push with bypass + GitHub->>SecretScan: Log bypass event + else Denied + Security-->>Dev: Bypass denied + Dev->>Dev: Remove secret and retry + end + else No Secret + SecretScan-->>GitHub: Clean + GitHub-->>Git: Push accepted + Git-->>Dev: Success + end +``` + +--- + +## CI/CD Pipeline Governance Architecture + +### GitHub Actions with Policy Enforcement + +```mermaid +graph TB + subgraph "Enterprise Policies" + EnterprisePolicy[Enterprise Policy
Allowed Actions List] + end + + subgraph "Organization Configuration" + OrgPolicy[Organization Settings
Actions Permissions] + RunnerGroup[Self-Hosted Runner Groups] + Secrets[Organization Secrets] + end + + subgraph "Repository" + Workflow[Workflow YAML] + RepoSecrets[Repository Secrets] + Environments[Environments] + end + + subgraph "Execution" + Runner[GitHub Runner] + Job1[Build Job] + Job2[Test Job] + Job3[Deploy Job] + end + + subgraph "Security Controls" + OIDC[OIDC Token] + Audit[Audit Logs] + ReviewGate[Required Reviewers] + end + + EnterprisePolicy --> OrgPolicy + OrgPolicy --> Workflow + + Workflow --> Job1 + Workflow --> Job2 + Workflow --> Job3 + + Job1 --> Runner + Job2 --> Runner + Job3 --> Runner + + RunnerGroup --> Runner + Secrets --> Job1 + RepoSecrets --> Job2 + Environments --> Job3 + + Job3 --> OIDC + Job3 --> ReviewGate + + Runner --> Audit + + style EnterprisePolicy fill:#6f42c1,color:#fff + style OrgPolicy fill:#0366d6,color:#fff + style ReviewGate fill:#dc3545,color:#fff + style OIDC fill:#28a745,color:#fff +``` + +### Deployment Pipeline with Environments + +```mermaid +graph LR + subgraph "Source" + Code[Code Repository] + end + + subgraph "Build & Test" + Build[Build] + Test[Unit Tests] + Scan[Security Scan] + end + + subgraph "Environments" + Dev[Development
Auto Deploy] + Staging[Staging
Required Reviewers] + Prod[Production
Required Reviewers
Wait Timer] + end + + Code --> Build + Build --> Test + Test --> Scan + + Scan --> Dev + Dev --> Staging + Staging --> Prod + + style Dev fill:#17a2b8,color:#fff + style Staging fill:#ffc107,color:#000 + style Prod fill:#dc3545,color:#fff +``` + +--- + +## Hybrid and Multi-Cloud Integration + +### GitHub Enterprise with On-Premises Systems + +```mermaid +graph TB + subgraph "GitHub Enterprise Cloud" + GHEC[GitHub Enterprise Cloud] + Repos[Repositories] + Actions[GitHub Actions] + end + + subgraph "Corporate Network" + subgraph "Identity" + OnPremIdP[On-Premises IdP] + ADConnect[AD Connect] + end + + subgraph "CI/CD" + SelfHosted[Self-Hosted Runners] + Artifacts[Artifact Storage] + end + + subgraph "Security" + Firewall[Firewall] + VPN[VPN Gateway] + SIEM[SIEM System] + end + end + + subgraph "Cloud Providers" + Azure[Azure] + AWS[AWS] + GCP[Google Cloud] + end + + OnPremIdP -->|SAML| GHEC + ADConnect -->|Sync| OnPremIdP + + GHEC -->|Webhook| SelfHosted + SelfHosted -->|Store| Artifacts + + Actions -->|OIDC| Azure + Actions -->|OIDC| AWS + Actions -->|OIDC| GCP + + GHEC -->|Audit Stream| SIEM + Firewall -->|IP Allow List| GHEC + VPN -.->|Secure Access| SelfHosted + + style GHEC fill:#0366d6,color:#fff + style OnPremIdP fill:#6f42c1,color:#fff + style SelfHosted fill:#28a745,color:#fff +``` + +--- + +## Migration Architecture + +### Migration from Other Platforms to GitHub Enterprise Cloud + +```mermaid +graph TB + subgraph "Source Platform" + SourceVCS[Source VCS
GitLab/Bitbucket/Azure DevOps] + SourceRepos[Repositories] + SourceIssues[Issues/Work Items] + SourceCI[CI/CD Pipelines] + end + + subgraph "Migration Tools" + GEI[GitHub Enterprise Importer] + Scripts[Custom Scripts] + API[REST/GraphQL API] + end + + subgraph "GitHub Enterprise Cloud" + subgraph "Target Structure" + Orgs[Organizations] + Repos[Repositories] + Teams[Teams] + end + + subgraph "Migrated Content" + Code[Source Code] + History[Git History] + Issues[Issues] + Workflows[GitHub Actions] + end + end + + subgraph "Post-Migration" + Validation[Validation] + Training[User Training] + Cutover[Production Cutover] + end + + SourceRepos -->|Git Clone/Push| GEI + SourceIssues -->|Export/Import| API + SourceCI -->|Translate| Scripts + + GEI --> Orgs + GEI --> Repos + API --> Issues + Scripts --> Workflows + + Repos --> Code + Repos --> History + Orgs --> Teams + + Code --> Validation + History --> Validation + Issues --> Validation + Workflows --> Validation + + Validation --> Training + Training --> Cutover + + style GEI fill:#0366d6,color:#fff + style Validation fill:#28a745,color:#fff + style Cutover fill:#dc3545,color:#fff +``` + +### Migration Phases + +```mermaid +gantt + title GitHub Enterprise Migration Timeline + dateFormat YYYY-MM-DD + section Planning + Assessment & Planning :p1, 2024-01-01, 30d + Pilot Organization Setup :p2, after p1, 14d + section Migration + Pilot Migration (10 repos) :m1, after p2, 14d + Wave 1 (100 repos) :m2, after m1, 21d + Wave 2 (500 repos) :m3, after m2, 21d + Wave 3 (Remaining) :m4, after m3, 30d + section Validation + Parallel Running :v1, after m2, 60d + User Training :v2, after m2, 45d + section Cutover + Production Cutover :c1, after v1, 7d + Decommission Old Platform :c2, after c1, 30d +``` + +--- + +## Quick Reference Cards + +### Permission Levels Quick Reference + +#### Repository Permissions + +| Level | Read | Write | Admin | +|-------|------|-------|-------| +| **Read** | ✅ View code
✅ Open issues
✅ Comment | ❌ | ❌ | +| **Triage** | ✅ Read access
✅ Manage issues
✅ Manage PRs | ❌ | ❌ | +| **Write** | ✅ Triage access
✅ Push commits
✅ Merge PRs | ✅ Push to branch
✅ Create releases | ❌ | +| **Maintain** | ✅ Write access
✅ Manage issues
✅ Manage releases | ✅ Push to protected
✅ Manage webhooks | ❌ Delete repo | +| **Admin** | ✅ Maintain access
✅ Full control | ✅ All write access | ✅ Delete repo
✅ Manage settings
✅ Manage access | + +#### Organization Roles + +| Role | Scope | Key Permissions | +|------|-------|-----------------| +| **Owner** | Organization | • Full admin access
• Manage all repos
• Manage members
• Configure SSO
• Access billing | +| **Billing Manager** | Billing only | • View billing info
• Update payment methods
• View usage reports | +| **Member** | Limited | • Create repos (if allowed)
• Create teams
• View members | +| **Moderator** | Content | • Block/unblock users
• Limit interactions
• Manage comments | + +#### Enterprise Roles + +| Role | Permissions | +|------|-------------| +| **Enterprise Owner** | • Full enterprise control
• Manage organizations
• Configure policies
• Access audit logs
• Manage billing | +| **Billing Manager** | • View/update billing
• View usage reports
• No organization access | +| **Member** | • Access via organization
• No enterprise settings | + +### Policy Inheritance Matrix + +```mermaid +graph TD + Enterprise[Enterprise Level
ENFORCED/ALLOWED/DISABLED] + Org[Organization Level
Can restrict if ALLOWED] + Repo[Repository Level
Can restrict if Org allows] + + Enterprise -->|ENFORCED| Org + Enterprise -->|ALLOWED| Org + Enterprise -->|DISABLED| Org + + Org -->|Org Policy| Repo + + style Enterprise fill:#6f42c1,color:#fff + style Org fill:#0366d6,color:#fff + style Repo fill:#28a745,color:#fff +``` + +| Policy | Enterprise | Organization | Repository | +|--------|-----------|--------------|------------| +| **Actions Permissions** | Allowed list | Can restrict further | Cannot override | +| **Repository Visibility** | Enforced/Allowed | Can restrict | Cannot override | +| **Forking** | Allowed/Disabled | Can disable | Cannot override | +| **GitHub Pages** | Enabled/Disabled | Can disable | Cannot override | +| **Branch Protection** | N/A | N/A | Full control | +| **Rulesets** | Via org policy | Applied to repos | Can add more rules | + +### Security Features Matrix + +| Feature | Free | Team | Enterprise with GHAS | +|---------|------|------|----------------------| +| **Dependabot Alerts** | Public repos | All repos | All repos | +| **Dependabot Security Updates** | Public repos | All repos | All repos | +| **Dependabot Version Updates** | ✅ | ✅ | ✅ | +| **Dependency Review** | Public repos | ❌ | ✅ | +| **Code Scanning (CodeQL)** | Public repos | ❌ | ✅ | +| **Secret Scanning** | Public repos | ❌ | ✅ | +| **Secret Push Protection** | Public repos | ❌ | ✅ | +| **Custom Secret Patterns** | ❌ | ❌ | ✅ | +| **Security Overview** | ❌ | ❌ | ✅ | + +### Rulesets vs Branch Protection + +| Feature | Branch Protection | Rulesets | +|---------|------------------|----------| +| **Scope** | Single branch pattern | Multiple branches/tags | +| **Organization-Wide** | ❌ | ✅ | +| **Bypass Actors** | Limited | ✅ Full control | +| **Status Checks** | ✅ | ✅ | +| **File Path Restrictions** | ❌ | ✅ | +| **Metadata Restrictions** | ❌ | ✅ (commit message, author) | +| **Import/Export** | ❌ | ✅ | +| **Evaluation Modes** | N/A | Active/Evaluate | + +### Common CLI Commands + +```bash +# GitHub CLI (gh) - Essential Commands + +# Authentication +gh auth login +gh auth status + +# Repository Management +gh repo create org/repo --public +gh repo clone org/repo +gh repo view org/repo + +# Organization Management +gh api orgs/my-org +gh api orgs/my-org/members + +# Team Management +gh api orgs/my-org/teams/my-team/members +gh api -X PUT orgs/my-org/teams/my-team/repos/my-org/my-repo + +# Security Alerts +gh api repos/my-org/my-repo/code-scanning/alerts +gh api repos/my-org/my-repo/secret-scanning/alerts +gh api repos/my-org/my-repo/dependabot/alerts + +# Audit Log (Enterprise) +gh api enterprises/my-enterprise/audit-log + +# Actions +gh workflow list +gh workflow run workflow.yml +gh run list +gh run view 1234567890 + +# Rulesets +gh api repos/my-org/my-repo/rulesets +gh api -X POST repos/my-org/my-repo/rulesets --input ruleset.json + +# Organization Policies +gh api -X PUT orgs/my-org/actions/permissions --field allowed_actions=selected +``` + +### Terraform Resource Quick Reference + +```hcl +# Essential GitHub Terraform Resources + +# Organization +resource "github_organization_settings" "main" { + billing_email = "billing@example.com" +} + +# Team +resource "github_team" "engineering" { + name = "engineering" + description = "Engineering team" + privacy = "closed" +} + +# Repository +resource "github_repository" "main" { + name = "my-repo" + visibility = "private" + auto_init = true +} + +# Team Repository Access +resource "github_team_repository" "main" { + team_id = github_team.engineering.id + repository = github_repository.main.name + permission = "push" +} + +# Branch Protection +resource "github_branch_protection" "main" { + repository_id = github_repository.main.node_id + pattern = "main" + + required_pull_request_reviews { + required_approving_review_count = 2 + } +} + +# Repository Ruleset +resource "github_repository_ruleset" "main" { + name = "main-protection" + repository = github_repository.main.name + target = "branch" + enforcement = "active" + + rules { + required_linear_history = true + required_signatures = true + } +} + +# Actions Secrets +resource "github_actions_organization_secret" "main" { + secret_name = "API_TOKEN" + visibility = "selected" + plaintext_value = var.api_token +} +``` + +--- + +## Architecture Decision Records + +### ADR-001: Choose EMU vs Personal Accounts + +**Status:** Template + +**Context:** Organizations must decide between Enterprise Managed Users (EMU) and personal accounts with SAML SSO. + +**Decision Factors:** + +| Factor | EMU | Personal Accounts | +|--------|-----|-------------------| +| Identity Control | ✅ Full control | ⚠️ Partial | +| External Collaboration | ⚠️ Limited | ✅ Full | +| Open Source Contributions | ❌ | ✅ | +| Compliance Requirements | ✅ Strong | ⚠️ Moderate | +| User Experience | ⚠️ Separate accounts | ✅ Single account | +| Implementation Complexity | ⚠️ Complex | ✅ Simple | + +**Recommendation:** +- **Choose EMU if:** Strict compliance, regulated industry, need full lifecycle control +- **Choose Personal Accounts if:** Open source contributions, external collaboration, developer experience priority + +### ADR-002: Single vs Multi-Organization + +**Status:** Template + +**Decision Factors:** + +| Factor | Single Org | Multi Org | +|--------|-----------|-----------| +| Simplicity | ✅ Simple | ⚠️ Complex | +| Environment Separation | ⚠️ Weak | ✅ Strong | +| Policy Management | ✅ Centralized | ⚠️ Distributed | +| Compliance Isolation | ⚠️ Limited | ✅ Strong | +| Cost | ✅ Lower | ⚠️ Higher | +| Scalability | ⚠️ Limited | ✅ High | + +**Recommendation:** +- **Single Org:** < 500 developers, simple governance, unified business unit +- **Multi Org:** > 500 developers, multiple environments, complex compliance, business unit separation + +--- + +## Integration Patterns + +### Pattern: SIEM Integration with Audit Log Streaming + +```mermaid +sequenceDiagram + participant GitHub as GitHub Enterprise + participant Stream as Audit Log Stream + participant SIEM as SIEM Platform + participant SOC as Security Operations + + GitHub->>Stream: Audit Event (HTTPS/JSON) + Stream->>SIEM: Forward Event + + alt Critical Event + SIEM->>SIEM: Correlate with other events + SIEM->>SOC: Generate Alert + SOC->>GitHub: Investigate (via API) + GitHub-->>SOC: Additional context + SOC->>SOC: Take remediation action + else Normal Event + SIEM->>SIEM: Store for compliance + end +``` + +### Pattern: Automated Compliance Reporting + +```mermaid +graph LR + subgraph "Data Collection" + API[GitHub API] + Audit[Audit Logs] + end + + subgraph "Processing" + ETL[ETL Pipeline] + Analytics[Analytics Engine] + end + + subgraph "Reporting" + Dashboard[Compliance Dashboard] + Reports[Automated Reports] + Alerts[Alert System] + end + + API --> ETL + Audit --> ETL + ETL --> Analytics + Analytics --> Dashboard + Analytics --> Reports + Analytics --> Alerts + + style API fill:#0366d6,color:#fff + style Analytics fill:#28a745,color:#fff + style Reports fill:#ffc107,color:#000 +``` + +--- + +## Summary + +This reference architecture document provides consolidated views of: + +1. **Complete Enterprise Architecture** - All components and relationships +2. **Organization Topologies** - Single, multi-org, and business unit patterns +3. **IAM Integration** - EMU and personal account flows +4. **Security Architecture** - GHAS features and scanning pipelines +5. **CI/CD Governance** - Actions policies and deployment patterns +6. **Hybrid Integration** - On-premises and multi-cloud connections +7. **Migration Patterns** - Moving to GitHub Enterprise Cloud +8. **Quick References** - Permissions, policies, CLI commands, and Terraform + +### Related Documentation + +- [Enterprise Hierarchy](01-enterprise-hierarchy.md) - Enterprise structure and roles +- [Organization Strategies](02-organization-strategies.md) - Org design patterns +- [Identity & Access Management](03-identity-access-management.md) - IAM configuration +- [Enterprise Managed Users](04-enterprise-managed-users.md) - EMU deep dive +- [Teams & Permissions](05-teams-permissions.md) - Team structures +- [Policy Inheritance](06-policy-inheritance.md) - Policy enforcement +- [Repository Governance](07-repository-governance.md) - Repo settings and rulesets +- [Security & Compliance](08-security-compliance.md) - GHAS and compliance +- [Best Practices & WAF](09-best-practices-waf.md) - Well-Architected Framework + +--- + +## References + +### Architecture Documentation +- [GitHub Enterprise Cloud Architecture](https://docs.github.com/en/enterprise-cloud@latest/admin) +- [GitHub Well-Architected Framework](https://wellarchitected.github.com/) +- [GitHub Enterprise Onboarding](https://docs.github.com/en/enterprise-cloud@latest/enterprise-onboarding) + +### Integration Guides +- [SAML Configuration](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam) +- [SCIM Provisioning](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users) +- [Audit Log Streaming](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise) + +### API References +- [GitHub REST API](https://docs.github.com/en/rest) +- [GitHub GraphQL API](https://docs.github.com/en/graphql) +- [GitHub CLI](https://cli.github.com/) + +### Terraform Provider +- [GitHub Terraform Provider](https://registry.terraform.io/providers/integrations/github/latest/docs) + +### Best Practices +- [Best Practices for Organizations](https://github.blog/enterprise-software/devops/best-practices-for-organizations-and-teams-using-github-enterprise-cloud/) +- [GitHub Enterprise Cloud eBook](https://assets.ctfassets.net/wfutmusr1t3h/ooXuGRtFrKHrFZ8cIdbUC/4333e8014b2e950d9381bdb102415e3a/GitHub-Enterprise-Cloud_ebook.pdf) diff --git a/docs/final-prompt-plan.md b/docs/final-prompt-plan.md new file mode 100644 index 0000000..b66274f --- /dev/null +++ b/docs/final-prompt-plan.md @@ -0,0 +1,512 @@ +# Final Prompt Plan: GitHub Enterprise Administration & Governance (L400) + +> **Level:** L400 Advanced Workshop +> **Scope:** GitHub Enterprise Cloud (GHEC) Administration & Governance +> **Output:** Comprehensive markdown documentation with Mermaid diagrams + +--- + +## Objective + +Create expert-level (L400) documentation for GitHub Enterprise Cloud administration and governance, covering enterprise hierarchy, organization strategies, IAM, policy inheritance, teams, and best practices aligned with the GitHub Well-Architected Framework. + +--- + +## Documentation Structure + +All files to be created in the `docs/` folder: + +``` +docs/ +├── final-prompt-plan.md # This plan (for reference) +├── 01-enterprise-hierarchy.md # Enterprise structure & hierarchy +├── 02-organization-strategies.md # Org patterns (single/red-green/sandbox/archive) +├── 03-identity-access-management.md # IAM, SAML SSO, SCIM overview +├── 04-enterprise-managed-users.md # EMU deep dive, advantages, best practices +├── 05-teams-permissions.md # Team structures & permission models +├── 06-policy-inheritance.md # Policy enforcement & inheritance flows +├── 07-repository-governance.md # Repo settings, rulesets, security +├── 08-security-compliance.md # Security features & compliance +├── 09-best-practices-waf.md # GitHub WAF principles & recommendations +└── 10-reference-architecture.md # Mermaid diagrams & architecture patterns +``` + +--- + +## Detailed File Specifications + +### 1. `01-enterprise-hierarchy.md` +**Purpose:** Explain the GHEC enterprise hierarchy and structural components + +**Content:** +- Enterprise account overview and capabilities +- Hierarchy levels: Enterprise → Organizations → Repositories +- Enterprise roles (Enterprise Owner, Billing Manager, Member) +- Enterprise settings and dashboard navigation +- Multi-organization management patterns +- Enterprise audit log and compliance features + +**Mermaid Diagrams:** +- Enterprise hierarchy tree diagram +- Enterprise admin responsibilities flow + +**Sources:** +- https://docs.github.com/en/enterprise-cloud@latest/admin +- https://docs.github.com/en/enterprise-cloud@latest/enterprise-onboarding +- https://resources.github.com/learn/pathways/administration-governance/essentials/administration-governance-github-enterprise-cloud/ + +--- + +### 2. `02-organization-strategies.md` +**Purpose:** Deep dive into organization design patterns and strategies + +**Content:** +- Single organization pattern + - When to use, pros/cons, scaling considerations +- Multi-organization patterns: + - **Red/Green (Blue/Green):** Production/development separation + - **Sandbox:** Innovation and experimentation environments + - **Archive:** Decommissioned/historical code management + - **Business Unit separation:** Department/team isolation + - **Compliance separation:** Regulatory boundary management +- Organization naming conventions +- Migration strategies between patterns +- Decision matrix for choosing organization strategy + +**Mermaid Diagrams:** +- Single org vs multi-org comparison +- Red-Green-Sandbox-Archive architecture pattern +- Organization lifecycle flow + +**Sources:** +- https://github.blog/enterprise-software/devops/best-practices-for-organizations-and-teams-using-github-enterprise-cloud/ +- https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings +- https://wellarchitected.github.com/library/overview/ + +--- + +### 3. `03-identity-access-management.md` +**Purpose:** IAM foundations, authentication methods, and enterprise type selection + +**Content:** +- Choosing an enterprise type: + - Enterprise with personal accounts + - Enterprise with managed users (EMU) + - Decision criteria and comparison matrix +- Authentication methods overview +- SAML Single Sign-On (SSO) configuration + - IdP setup (Microsoft Entra ID, Okta, PingFederate, etc.) + - SAML attribute mapping + - SSO enforcement and recovery +- SCIM provisioning fundamentals + - Automated user lifecycle management + - Group synchronization + - Deprovisioning workflows +- Personal Access Tokens (PAT) policies +- SSH key and GPG key management +- Two-factor authentication (2FA) enforcement +- Cross-reference to [Enterprise Managed Users deep dive](04-enterprise-managed-users.md) + +**Mermaid Diagrams:** +- Enterprise type decision flowchart +- IAM authentication flow +- SCIM provisioning lifecycle + +**Sources:** +- https://docs.github.com/en/enterprise-cloud@latest/admin/concepts/identity-and-access-management/enterprise-managed-users +- https://docs.github.com/en/enterprise-cloud@latest/enterprise-onboarding/getting-started-with-your-enterprise/choose-an-enterprise-type +- https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users + +--- + +### 4. `04-enterprise-managed-users.md` +**Purpose:** Comprehensive deep dive into Enterprise Managed Users (EMU) - advantages, configuration, and best practices + +**Content:** +- **EMU Overview and Value Proposition** + - What are Enterprise Managed Users? + - EMU architecture and how it differs from personal accounts + - Complete identity lifecycle management from IdP + - Account naming conventions (_shortcode suffix) + +- **Key Advantages of EMU** + - **Centralized Identity Control:** Users provisioned/deprovisioned exclusively via IdP + - **Enhanced Security Posture:** No personal accounts mixing with enterprise data + - **Simplified Offboarding:** Automatic access revocation when removed from IdP + - **Compliance Benefits:** Full audit trail, no shadow IT accounts + - **Namespace Isolation:** Clear separation between work and personal GitHub + - **Policy Enforcement:** Guaranteed enforcement of enterprise policies + - **IP Allow Lists:** Restrict access to corporate networks + - **Reduced Attack Surface:** No PAT/SSH key sprawl from personal accounts + +- **EMU vs Personal Accounts Comparison** + - Feature comparison table + - Use case scenarios for each + - Migration considerations + - Hybrid scenarios (when applicable) + +- **EMU Limitations and Considerations** + - Cannot contribute to public repositories outside the enterprise + - Cannot fork repositories to personal namespaces + - Cannot create public gists + - Limited GitHub Marketplace app access + - No GitHub Sponsors participation + - Username format restrictions (_shortcode) + - Cannot be invited to organizations outside the enterprise + +- **Supported Identity Providers** + - Microsoft Entra ID (Azure AD) - full support + - Okta - full support + - PingFederate - full support + - Partner IdP integrations + - OIDC vs SAML considerations + +- **EMU Configuration Best Practices** + - IdP group mapping strategies + - Team synchronization setup + - Role-based access control patterns + - Naming conventions and organization + - Handling contractors and external collaborators + - Guest access patterns + +- **EMU Migration Strategies** + - From personal accounts enterprise to EMU + - Repository migration approaches + - User communication and change management + - Parallel operation during transition + - Rollback considerations + +- **EMU Operational Excellence** + - Monitoring and alerting + - Troubleshooting common issues + - IdP sync failures and recovery + - Audit log analysis for EMU events + +**Mermaid Diagrams:** +- EMU architecture overview (IdP → SCIM → GitHub Enterprise) +- EMU vs Personal accounts feature comparison +- EMU user lifecycle flow (provision → active → deprovision) +- EMU decision tree (should you use EMU?) +- IdP group to GitHub team synchronization flow + +**Sources:** +- https://docs.github.com/en/enterprise-cloud@latest/admin/concepts/identity-and-access-management/enterprise-managed-users +- https://docs.github.com/en/enterprise-cloud@latest/enterprise-onboarding/getting-started-with-your-enterprise/choose-an-enterprise-type +- https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users +- https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users +- https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts + +--- + +### 5. `05-teams-permissions.md` +**Purpose:** Team structures, nested teams, and permission models + +**Content:** +- Team types and visibility (visible, secret) +- Nested teams and hierarchy + - Parent/child team inheritance + - Permission cascading +- Team synchronization with IdP groups +- Permission levels: + - Repository: Read, Triage, Write, Maintain, Admin + - Organization: Member, Moderator, Billing Manager, Owner + - Enterprise: Member, Billing Manager, Owner +- Custom repository roles +- Base permissions configuration +- CODEOWNERS and automatic review assignment +- Team maintainers vs organization owners + +**Mermaid Diagrams:** +- Team hierarchy and inheritance +- Permission levels matrix +- Team sync with IdP flow + +**Sources:** +- https://docs.github.com/en/enterprise-cloud@latest/organizations/organizing-members-into-teams +- https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization + +--- + +### 6. `06-policy-inheritance.md` +**Purpose:** Policy enforcement and inheritance across the enterprise hierarchy + +**Content:** +- Policy enforcement levels: + - Enterprise-level policies (enforced, allowed, disabled) + - Organization-level policies + - Repository-level settings +- Inheritance and override rules +- Key policy areas: + - Repository creation and visibility + - Repository forking policies + - GitHub Actions permissions + - GitHub Copilot policies + - GitHub Pages policies + - Project visibility + - Member privileges +- Policy conflicts and resolution +- Audit and compliance monitoring of policy changes + +**Mermaid Diagrams:** +- Policy inheritance flow (Enterprise → Org → Repo) +- Policy enforcement decision tree +- Actions policy inheritance example + +**Sources:** +- https://docs.github.com/en/enterprise-cloud@latest/admin/enforcing-policies +- https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings + +--- + +### 7. `07-repository-governance.md` +**Purpose:** Repository settings, rulesets, and governance at scale + +**Content:** +- Repository visibility (public, private, internal) +- Repository templates and standardization +- Branch protection rules vs Repository rulesets + - Rulesets advantages (org-wide, bypass actors, import/export) + - Ruleset targeting (branches, tags) + - Required status checks + - Required reviews and CODEOWNERS + - Signed commits requirement +- Tag protection rules +- Push rulesets and file path restrictions +- Merge strategies and settings +- Repository archival and transfer policies +- Innersource patterns with internal repositories + +**Mermaid Diagrams:** +- Branch protection vs Rulesets comparison +- Repository lifecycle (create → active → archive) +- Merge queue flow + +**Sources:** +- https://docs.github.com/en/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features +- https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule + +--- + +### 8. `08-security-compliance.md` +**Purpose:** Security features, code security, and compliance capabilities + +**Content:** +- GitHub Advanced Security (GHAS) overview +- Code scanning with CodeQL + - Default setup vs advanced configuration + - Custom queries and severity levels +- Secret scanning + - Supported patterns + - Push protection + - Custom patterns +- Dependency management + - Dependabot alerts and updates + - Dependency review + - Dependency graph +- Security policies (SECURITY.md) +- Private vulnerability reporting +- Security advisories +- Audit log and SIEM integration + - Audit log streaming + - API access for compliance +- Compliance certifications (SOC2, FedRAMP, etc.) + +**Mermaid Diagrams:** +- Security scanning pipeline flow +- Secret scanning with push protection +- Compliance audit flow + +**Sources:** +- https://docs.github.com/en/actions/security-guides +- https://docs.github.com/en/enterprise-cloud@latest/admin + +--- + +### 9. `09-best-practices-waf.md` +**Purpose:** GitHub Well-Architected Framework principles and recommendations + +**Content:** +- GitHub WAF pillars overview: + - Reliability + - Security + - Operational Excellence + - Performance Efficiency + - Cost Optimization +- Enterprise setup checklist +- Organization design recommendations +- Repository naming and structure conventions +- Branching strategy recommendations +- CI/CD governance best practices +- Change management processes +- Disaster recovery and backup strategies +- Scaling patterns for large enterprises +- Common anti-patterns to avoid + +**Mermaid Diagrams:** +- WAF pillars relationship +- Enterprise maturity model +- Recommended CI/CD governance flow + +**Sources:** +- https://wellarchitected.github.com/library/overview/ +- https://github.blog/enterprise-software/devops/best-practices-for-organizations-and-teams-using-github-enterprise-cloud/ +- https://assets.ctfassets.net/wfutmusr1t3h/ooXuGRtFrKHrFZ8cIdbUC/4333e8014b2e950d9381bdb102415e3a/GitHub-Enterprise-Cloud_ebook.pdf + +--- + +### 10. `10-reference-architecture.md` +**Purpose:** Consolidated architecture diagrams and reference patterns + +**Content:** +- Complete enterprise architecture diagram +- Organization topology patterns +- IAM integration architecture +- Security scanning architecture +- CI/CD pipeline governance architecture +- Hybrid/multi-cloud integration patterns +- Migration architecture (from other platforms) +- Quick reference cards for: + - Permission levels + - Policy inheritance + - Team structures + - Security features + +**Mermaid Diagrams:** +- Complete GHEC reference architecture +- Enterprise topology with all components +- Integration architecture (IdP, SIEM, CI/CD) + +**Sources:** +- All above sources consolidated + +--- + +## Implementation Instructions + +### For the Agentic Implementation: + +1. **Fetch all source URLs** listed in the initial-prompt.md and extract relevant content for each section + +2. **Create files sequentially** (01 through 09) ensuring each file: + - Has proper H1 title and introduction + - Uses H2/H3 for logical sections + - Includes relevant Mermaid diagrams (```mermaid blocks) + - Has a References section at the end with source URLs + - Cross-links to related documentation files where appropriate + +3. **Mermaid diagram requirements:** + - Use `graph TD` or `graph LR` for hierarchies and flows + - Use `sequenceDiagram` for authentication/process flows + - Use `flowchart` for decision trees + - Include descriptive node labels + +4. **Quality criteria:** + - L400 depth: Expert-level content with technical details + - Actionable: Include specific configuration steps where applicable + - Complete: Cover all aspects mentioned in each file specification + - Current: Use latest GHEC features (rulesets, push protection, etc.) + +5. **Cross-linking rules:** + - Link between docs/ files using relative paths: `[Teams and Permissions](04-teams-permissions.md)` + - Reference existing labs only where they provide hands-on practice for concepts + - Don't duplicate lab content in documentation + +6. **Do NOT stop until:** + - All 10 documentation files are created + - Each file has at least 2 Mermaid diagrams + - All References sections are populated + - README.md is updated with links to new documentation + +--- + +## README.md Update Required + +**IMPORTANT:** Add the new section at the **BEGINNING** of README.md, before existing content. The existing hands-on labs content should come AFTER this new documentation section. + +```markdown +# GitHub Administration & Governance Workshop (L400) + +> **Advanced Workshop** | Expert-level training for GitHub Enterprise Cloud administration, governance, and best practices. This workshop covers enterprise hierarchy, organization strategies, identity management (including Enterprise Managed Users), policy enforcement, security compliance, and the GitHub Well-Architected Framework. + +## Workshop Documentation + +### Enterprise Administration +- [Enterprise Hierarchy](docs/01-enterprise-hierarchy.md) - GHEC structure, roles, and multi-org management +- [Organization Strategies](docs/02-organization-strategies.md) - Single/multi-org patterns, red-green-sandbox-archive + +### Identity & Access Management +- [Identity & Access Management](docs/03-identity-access-management.md) - SAML SSO, SCIM, enterprise type selection +- [Enterprise Managed Users (EMU)](docs/04-enterprise-managed-users.md) - EMU deep dive, advantages, best practices ⭐ + +### Teams & Permissions +- [Teams and Permissions](docs/05-teams-permissions.md) - Team structures, nested teams, permission models +- [Policy Inheritance](docs/06-policy-inheritance.md) - Enterprise → Org → Repo policy enforcement + +### Repository Governance +- [Repository Governance](docs/07-repository-governance.md) - Rulesets, branch protection, templates +- [Security & Compliance](docs/08-security-compliance.md) - GHAS, code scanning, audit logs + +### Best Practices & Architecture +- [Best Practices & WAF](docs/09-best-practices-waf.md) - GitHub Well-Architected Framework principles +- [Reference Architecture](docs/10-reference-architecture.md) - Architecture diagrams and patterns + +--- + +## Hands-on Labs + + +``` + +The existing README.md content (starting from "# gh-abcs-admin") should be restructured to fit under the "Hands-on Labs" section or renamed appropriately to complement the new L400 documentation. + +--- + +## Execution Checklist + +- [ ] Create `docs/01-enterprise-hierarchy.md` +- [ ] Create `docs/02-organization-strategies.md` +- [ ] Create `docs/03-identity-access-management.md` +- [ ] Create `docs/04-enterprise-managed-users.md` +- [ ] Create `docs/05-teams-permissions.md` +- [ ] Create `docs/06-policy-inheritance.md` +- [ ] Create `docs/07-repository-governance.md` +- [ ] Create `docs/08-security-compliance.md` +- [ ] Create `docs/09-best-practices-waf.md` +- [ ] Create `docs/10-reference-architecture.md` +- [ ] Update `README.md` with documentation links +- [ ] Verify all cross-links work +- [ ] Ensure all Mermaid diagrams render correctly + +--- + +## References + +Primary sources for this documentation: + +### Enterprise & Administration +- https://resources.github.com/learn/pathways/administration-governance/essentials/administration-governance-github-enterprise-cloud/ +- https://docs.github.com/en/enterprise-cloud@latest/enterprise-onboarding +- https://docs.github.com/en/enterprise-cloud@latest/admin +- https://docs.github.com/en/enterprise-cloud@latest/enterprise-onboarding/getting-started-with-your-enterprise/choose-an-enterprise-type + +### Enterprise Managed Users (EMU) +- https://docs.github.com/en/enterprise-cloud@latest/admin/concepts/identity-and-access-management/enterprise-managed-users +- https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users +- https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users +- https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts + +### Organizations & Teams +- https://docs.github.com/en/enterprise-cloud@latest/organizations +- https://docs.github.com/en/enterprise-cloud@latest/organizations/organizing-members-into-teams +- https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings + +### Repositories & Policies +- https://docs.github.com/en/enterprise-cloud@latest/repositories +- https://docs.github.com/en/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features +- https://docs.github.com/en/enterprise-cloud@latest/admin/enforcing-policies + +### Best Practices & Architecture +- https://docs.github.com/en/enterprise-cloud@latest/admin/concepts/enterprise-best-practices/organize-work +- https://github.blog/enterprise-software/devops/best-practices-for-organizations-and-teams-using-github-enterprise-cloud/ +- https://wellarchitected.github.com/library/overview/ +- https://assets.ctfassets.net/wfutmusr1t3h/ooXuGRtFrKHrFZ8cIdbUC/4333e8014b2e950d9381bdb102415e3a/GitHub-Enterprise-Cloud_ebook.pdf diff --git a/docs/initial-prompt.md b/docs/initial-prompt.md new file mode 100644 index 0000000..1e24532 --- /dev/null +++ b/docs/initial-prompt.md @@ -0,0 +1,37 @@ +You are a co-engineer tasked with creating comprehensive documentation for GitHub Administration and Governance. Use your judgment, stay curious, and act with care. + +Using the GitHub documentation and located here and in the Additional Resources of each section: +- https://resources.github.com/learn/pathways/administration-governance/essentials/administration-governance-github-enterprise-cloud/ +- https://docs.github.com/en/enterprise-cloud@latest/enterprise-onboarding +- https://docs.github.com/en/enterprise-cloud@latest/admin +- https://docs.github.com/en/enterprise-cloud@latest/organizations +- https://docs.github.com/en/enterprise-cloud@latest/repositories +- https://docs.github.com/en/enterprise-cloud@latest/organizations/organizing-members-into-teams +- https://docs.github.com/en/enterprise-cloud@latest/admin/enforcing-policies +- https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings +- https://docs.github.com/en/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features +- https://docs.github.com/en/enterprise-cloud@latest/admin/concepts/enterprise-best-practices/organize-work +- https://github.blog/enterprise-software/devops/best-practices-for-organizations-and-teams-using-github-enterprise-cloud/ +- https://assets.ctfassets.net/wfutmusr1t3h/ooXuGRtFrKHrFZ8cIdbUC/4333e8014b2e950d9381bdb102415e3a/GitHub-Enterprise-Cloud_ebook.pdf + +Create a comprehensive markdown documentation for setting and configuring policies for a GHEC enterprise account, organisations and repositories. + +Use the best practices and the GitHub WAF principles to guide the setup process. +https://wellarchitected.github.com/library/overview/ + +Evaluate if there are any specific configurations or best practices that should be followed during the setup. + +Use mermaid diagram when needed to describe the flow and how the service works. + +Use public GitHub and Microsoft Learn and Microsoft Docs. + +Create sections and subsections as needed to ensure clarity and completeness. + +Create multiple files if needed to ensure each section is manageable in size. + +Reference the sources used in each markdown documentation at the end as References. +If you need to reference other sources, use official GitHub and Microsoft sources. + +Take your time, and come up with a plan, then execute your plan. + +DONT STOP until you are 100% sure you got all the required information for GitHub Administration and Governance. \ No newline at end of file