Skip to content

11-security-by-default-policies.md

Latest commit

 

History

History
325 lines (252 loc) · 53.1 KB

11-security-by-default-policies.md

File metadata and controls

325 lines (252 loc) · 53.1 KB

GitHub Security-by-Default: Policies and Settings Recommendations

This document provides comprehensive security policy and settings recommendations for GitHub Enterprise Cloud across three hierarchical levels: Enterprise, Organization, and Repository. Following these recommendations will help establish a strong security posture following the principle of "security by default."

Document status

  • Last reviewed: 2026-05-19
  • Authorship: Drafted with AI assistance (GitHub Copilot, multi-model review) and reviewed by a human maintainer before publication.
  • Sources: Based on public documentation — primarily docs.github.com, learn.microsoft.com, and official vendor blogs cited inline.
  • Verify before acting: GitHub and Microsoft update product documentation continuously. Re-confirm against the live source pages before relying on this content for production decisions.

⚠️ Important Compliance Note: These recommendations are based on official GitHub documentation and the GitHub Well-Architected Framework. Settings may vary based on your enterprise type (EMU vs. standard), compliance requirements, and organizational needs. Always verify current documentation at docs.github.com before implementing. Some policies behave differently for Enterprise Managed Users (EMU) enterprises vs. standard enterprises.

Table of Contents

  1. Enterprise Level Policies
  2. Organization Level Settings
  3. Repository Level Settings
  4. References

Enterprise Level Policies

Enterprise policies provide the highest level of governance and cascade down to all organizations and repositories. Enforcing policies at this level ensures consistent security controls across your entire enterprise.

Identity and Access Management

Level Policy/Setting Description Recommended Setting Reference
Enterprise Enterprise Managed Users (EMU) Centrally managed user accounts controlled through your identity provider Enable - Use EMU for centralized identity management, ensuring all users are provisioned/deprovisioned through IdP About Enterprise Managed Users
Enterprise SAML Single Sign-On Requires authentication through external identity provider Require - Enforce SAML SSO for all organizations in the enterprise About SAML for Enterprise IAM
Enterprise Two-Factor Authentication Requires 2FA for all organization members Require - Enforce 2FA for all members across the enterprise. Note: This policy is not available for EMU enterprises (EMU users authenticate via IdP) Enforcing policies for security settings
Enterprise Secure 2FA Methods Requires secure 2FA methods (passkeys, security keys, authenticator apps, GitHub mobile) Require - Only allow secure 2FA methods; disallow SMS-based 2FA. Note: This policy is not available for EMU enterprises Requiring secure methods of two-factor authentication
Enterprise IP Allow List Restricts access to enterprise resources from specified IP addresses Enable - Configure IP allow list with corporate network ranges Restricting network traffic with IP allow list
Enterprise SSH Certificate Authorities Manage SSH certificates for repository access Configure - Add SSH CA for certificate-based authentication; upgrade CAs to require certificate expiration Managing SSH certificate authorities
Enterprise SSO Auto-Redirect (EMU) Automatically redirects unauthenticated users to IdP sign-in Enable (for EMU) - Redirect users to SSO instead of showing 404 errors Managing SSO for unauthenticated users

Repository Management Policies

Level Policy/Setting Description Recommended Setting Reference
Enterprise Base Repository Permissions Default access level for all organization members None - Set to "No permission" to enforce least privilege principle Enforcing a policy for base repository permissions
Enterprise Repository Creation Controls who can create repositories Restrict - Limit to Organization Owners or use automated repository creation workflows Enforcing a policy for repository creation
Enterprise Block User Namespace Repositories Prevents EMU users from creating personal repositories Enable - Block creation of user namespace repositories for EMU enterprises Enforcing a policy for repository creation
Enterprise Public Repository Creation Controls creation of public repositories Disable - Prevent members from creating public repositories GitHub Well-Architected - Governance Policies
Enterprise Repository Visibility Change Controls who can change repository visibility Restrict to Organization Owners - Prevent accidental exposure of private code Enforcing a policy for changes to repository visibility
Enterprise Repository Deletion and Transfer Controls who can delete or transfer repositories Restrict to Organization Owners - Prevent accidental data loss Enforcing a policy for repository deletion and transfer
Enterprise Repository Forking Controls forking of private/internal repositories Restrict - Allow forking only within the same organization or disable if not needed. Note: If EMU blocks user namespace repos and forking is allowed, users cannot fork to their user accounts regardless of this policy Enforcing a policy for forking private or internal repositories
Enterprise Default Branch Name Sets the default branch name for new repositories Enforce - Set consistent default branch name (e.g., main) across enterprise Enforcing a policy for the default branch name
Enterprise Outside Collaborators Controls who can invite external collaborators Restrict to Enterprise/Organization Owners - Centralize control over external access Enforcing a policy for inviting outside collaborators
Enterprise Deploy Keys Controls creation and use of deploy keys Restrict - Consider restricting or using GitHub Apps instead for better access control. Warning: Changing to disabled will disable existing deploy keys in all repositories Enforcing a policy for deploy keys
Enterprise Issue Deletion Controls who can delete issues in repositories Restrict to Organization Owners - Prevent loss of issue history Enforcing a policy for deleting issues

Code Security and Analysis Policies

Level Policy/Setting Description Recommended Setting Reference
Enterprise GitHub Advanced Security Controls availability of GHAS features (GitHub Secret Protection, GitHub Code Security, GitHub Code Quality (public preview)). Note: GitHub Code Quality is in public preview as of mid-2026; availability and billing may differ from GA products. Enable for all organizations - Allow organizations to enable advanced security features. Note: This policy only impacts repository administrators; organization owners and security managers can always enable security features Enforcing policies for code security and analysis
Enterprise Dependabot Alerts Controls who can enable/disable Dependabot alerts Allow - Enable for repository admins to manage Dependabot alerts Enforcing a policy to manage the use of Dependabot alerts
Enterprise Secret Scanning Automatically scans for exposed secrets Enable - Enable secret scanning across all repositories About Secret Scanning
Enterprise Code Scanning (CodeQL) Automated security analysis of code Enable - Enable CodeQL analysis for supported languages About code scanning with CodeQL
Enterprise Dependency Insights Visibility Controls visibility of dependency insights Enable - Allow organization members to view dependency insights Enforcing a policy for visibility of dependency insights
Enterprise Copilot Autofix AI-powered security fix suggestions for code scanning results Enable - Allow Copilot Autofix for code security results. Note: This policy controls Autofix for code scanning security queries only; Copilot Autofix is integral to GitHub Code Quality and cannot be disabled for that feature Enforcing a policy for Copilot Autofix
Enterprise AI Detection for Secret Scanning Uses AI to detect generic passwords and secrets Enable - Allow AI detection to find passwords and unstructured secrets. Note: This policy requires that repository administrators are allowed to enable Secret Protection (controlled by a separate policy) Enforcing a policy for AI detection

GitHub Actions Policies

Level Policy/Setting Description Recommended Setting Reference
Enterprise Actions Availability Controls which organizations can use GitHub Actions Enable for all organizations - Allow Actions while enforcing other restrictions Enforcing policies for GitHub Actions
Enterprise Allowed Actions Controls which actions can be used Restrict - Allow only enterprise actions, GitHub actions, and explicitly allowlisted actions (do not rely on verified creators) Controlling access to public actions
Enterprise Require Actions SHA Pinning Requires actions to be pinned to full commit SHA Enable - Require full-length commit SHA for all actions Enforcing policies for GitHub Actions
Enterprise Default Workflow Permissions Controls default GITHUB_TOKEN permissions Read-only - Set to read-only for all scopes. Note: Enterprises created on or after February 2, 2023 default to read-only; older enterprises may default to read-write Workflow permissions
Enterprise Allow Actions to Create PRs Controls if Actions can create/approve PRs Disable - Prevent GITHUB_TOKEN from creating/approving pull requests Workflow permissions
Enterprise Fork Pull Request Workflows Controls workflow execution from fork PRs Require approval for all outside collaborators - Prevent malicious workflow execution. Note: Workflows triggered by pull_request_target events always run regardless of approval settings Fork pull request workflows from outside collaborators
Enterprise Repository-Level Runners Controls creation of repository-level self-hosted runners Disable - Prevent repository-level self-hosted runners; use org/enterprise level for better security control. Self-hosted runners at repository level pose risks as they may be compromised by untrusted code Runners policy

Personal Access Token Policies

Level Policy/Setting Description Recommended Setting Reference
Enterprise Fine-Grained PAT Access Controls fine-grained PAT access to resources Allow with approval - Require approval for fine-grained PATs Enforcing policies for personal access tokens
Enterprise PAT (Classic) Access Controls classic PAT access to resources Restrict - Consider restricting or blocking classic PATs in favor of fine-grained PATs Restricting access by personal access tokens
Enterprise PAT Maximum Lifetime Sets maximum lifetime for PATs Enable - Set maximum lifetime (e.g., 90-365 days) to limit exposure window. Note: For fine-grained PATs, the default maximum lifetime is 366 days. Classic PATs do not have an expiration requirement by default Enforcing a maximum lifetime policy
Enterprise Fine-Grained PAT Approval Requires approval for fine-grained PATs Require approval - Require organization owner approval for PATs Enforcing an approval policy

GitHub Copilot Policies

Level Policy/Setting Description Recommended Setting Reference
Enterprise Copilot Availability Controls which organizations can use Copilot Configure per organization - Enable based on licensing and compliance needs Managing Copilot policies
Enterprise Copilot in IDE Controls code completion in IDEs Enable - Allow for licensed users GitHub Copilot policies
Enterprise Copilot in GitHub.com Controls Copilot features on github.com Enable - Allow Copilot Chat on GitHub.com Managing Copilot policies
Enterprise Copilot Chat in IDE Controls Copilot Chat availability Enable - Allow Chat for code assistance GitHub Copilot policies
Enterprise Copilot CLI Controls Copilot in command line Enable - Allow CLI assistance GitHub Copilot policies
Enterprise Suggestions Matching Public Code Controls blocking of suggestions matching public code Block - Prevent suggestions identical to public code Managing Copilot policies
Enterprise User Feedback Collection Allows collection of user feedback Optional - Enable if participating in product improvement Managing Copilot policies
Enterprise Preview Features Allows access to preview Copilot features Disable - Avoid preview features in production unless needed Managing Copilot policies

Audit and Compliance

Level Policy/Setting Description Recommended Setting Reference
Enterprise Audit Log Streaming Streams audit logs to external SIEM/storage Enable - Configure audit log streaming to your SIEM for monitoring and compliance Streaming the audit log
Enterprise Verified Domains Verifies ownership of email domains Configure - Verify company domains to restrict notifications and add credibility Verifying or approving a domain

Organization Level Settings

Organization settings provide granular control within the boundaries set by enterprise policies. These settings should complement enterprise policies while allowing necessary flexibility.

Access and Permissions

Level Policy/Setting Description Recommended Setting Reference
Organization Base Repository Permissions Default access for organization members No permission or Read - Follow least privilege; use Read for innersource. Note: Internal repositories have a minimum visibility of read even if base permission is set to none Managing base permissions
Organization Member Privileges Controls what members can do in the organization Restrict - Limit member capabilities to necessary functions Managing organization settings
Organization Team Creation Permissions Controls who can create teams Restrict to Organization Admins - Centralize team management Setting team creation permissions
Organization Team Synchronization Syncs teams with IdP groups Enable - Sync teams with IdP groups for automatic provisioning Managing team synchronization
Organization Outside Collaborator Permissions Controls adding outside collaborators Restrict - Require organization owner approval Setting permissions for adding outside collaborators

Repository Governance

Level Policy/Setting Description Recommended Setting Reference
Organization Default Repository Visibility Default visibility for new repositories Internal - Default to internal for innersource; prevent accidental public repos Governing how people use repositories
Organization Repository Forking Policy Controls forking within the organization Restrict - Allow forking only within the same organization Managing the forking policy
Organization Repository Visibility Changes Controls who can change visibility Restrict - Only allow organization owners to change visibility Restricting repository visibility changes
Organization Repository Deletion Permissions Controls who can delete repositories Restrict - Only allow organization owners to delete repositories Setting permissions for deleting or transferring repositories
Organization Issue Deletion Controls who can delete issues Restrict - Only allow organization owners to delete issues Allowing people to delete issues

Repository Rulesets (Organization Level)

Level Policy/Setting Description Recommended Setting Reference
Organization Organization Rulesets Centralized branch/tag protection rules Enable - Create organization-wide rulesets for consistent protection Creating rulesets for repositories in your organization
Organization Ruleset Bypass Permissions Controls who can bypass rulesets Restrict - Limit bypass to specific roles with documented procedures Managing rulesets
Organization Custom Properties Metadata for repository classification Define - Create properties for security tier, compliance, production status Managing custom properties

Security Features

Level Policy/Setting Description Recommended Setting Reference
Organization Security Configurations Organization-wide security settings Enable default configuration - Apply consistent security settings to all repositories Creating a security configuration
Organization Dependency Graph Visualizes repository dependencies Enable - Enable for all repositories About the dependency graph
Organization Dependabot Alerts Alerts for vulnerable dependencies Enable - Enable for all repositories About Dependabot alerts
Organization Dependabot Security Updates Automatic PRs for security fixes Enable - Enable automatic security updates About Dependabot security updates
Organization Secret Scanning Detects exposed secrets Enable - Enable for all repositories About secret scanning
Organization Push Protection Blocks pushes containing secrets Enable - Enable push protection for all repositories About push protection
Organization Push Protection Bypass Controls who can bypass push protection Restrict - Limit bypass to specific roles/teams GitHub Well-Architected - Governance Policies
Organization Custom Secret Patterns Define custom patterns for organization-specific secrets Configure - Add patterns for internal tokens, API keys, credentials Defining custom patterns
Organization Non-Provider Pattern Detection Detect generic secrets like private keys Enable - Enable detection of SSH keys, PGP keys, connection strings Supported secret scanning patterns
Organization Code Scanning Automated code security analysis Enable - Enable default setup for all repositories About code scanning

GitHub Actions (Organization Level)

Level Policy/Setting Description Recommended Setting Reference
Organization Actions Permissions Controls which actions can run Restrict - Allow only explicitly allowlisted actions (do not rely on verified creators) Disabling or limiting GitHub Actions
Organization Runner Groups Organizes self-hosted runners Configure - Create runner groups limited to specific repositories GitHub Well-Architected - Governance Policies
Organization Required Workflows Enforces workflows across repositories Configure - Define required security/compliance workflows Required workflows

Webhooks and Integrations

Level Policy/Setting Description Recommended Setting Reference
Organization Webhook Secrets Authenticates webhook payloads Required - Always configure webhooks with secrets GitHub Well-Architected - Governance Policies
Organization Webhook SSL Verification Validates SSL for webhook endpoints Enable - Configure webhooks to use SSL GitHub Well-Architected - Governance Policies
Organization GitHub App Permissions Controls installed app permissions Review - Audit and minimize app permissions regularly Managing GitHub App installations

Repository Level Settings

Repository settings provide the most granular control for individual repositories. These should be configured to meet specific project needs while adhering to organization and enterprise policies.

Branch Protection and Rulesets

Level Policy/Setting Description Recommended Setting Reference
Repository Ruleset - Require Pull Request Requires PRs before merging Enable - Require PRs for default/protected branches About rulesets
Repository Ruleset - Required Approvals Number of required PR approvals At least 1 (2+ for production) - Enforce peer review Rulesets Best Practices
Repository Ruleset - Dismiss Stale Approvals Invalidates approvals on new commits Enable - Ensure approvals apply to final code Rulesets Best Practices
Repository Ruleset - Require CODEOWNERS Review Requires approval from code owners Enable - Ensure domain experts review changes About code owners
Repository Ruleset - Require Conversation Resolution Requires resolving review comments Enable - Ensure feedback is addressed Rulesets Best Practices
Repository Ruleset - Block Force Pushes Prevents force pushes to protected branches Enable - Protect commit history integrity Rulesets Best Practices
Repository Ruleset - Block Branch Deletion Prevents deletion of protected branches Enable - Protect important branches from deletion Rulesets Best Practices
Repository Ruleset - Require Signed Commits Requires GPG/SSH signed commits Enable (if adoption ≥80%) - Ensure commit authenticity. Note: Consider organizational readiness before enforcing; developers need signing keys configured Rulesets Best Practices
Repository Ruleset - Require Up-to-Date Branches Requires branch to be current before merging Enable - Ensure CI runs on final merged code Rulesets Best Practices
Repository Ruleset - Required Status Checks Requires CI/security checks to pass Enable - Configure required CI, security, and compliance checks About rulesets
Repository Ruleset - Require Code Scanning Results Requires code scanning to pass Enable - Block merges with high/critical severity findings Rulesets Best Practices
Repository Ruleset - Bypass Permissions Controls who can bypass rules Restrict - Limit bypass to emergency situations with audit About rulesets

Push Rules (Push Rulesets)

Level Policy/Setting Description Recommended Setting Reference
Repository Restrict File Paths Blocks changes to sensitive paths Configure - Protect .github/, security configs, CI/CD files Available rules for rulesets
Repository Restrict File Extensions Blocks specific file types Configure - Block executables, binaries (.exe, .dll, etc.) Rulesets Best Practices
Repository Restrict File Size Limits maximum file size Configure - Set appropriate limits to prevent large files Rulesets Best Practices

Security Features (Repository Level)

Level Policy/Setting Description Recommended Setting Reference
Repository Dependency Graph Tracks repository dependencies Enable - Enable for dependency visibility About the dependency graph
Repository Dependabot Alerts Alerts for vulnerable dependencies Enable - Enable and monitor alerts Managing security and analysis settings
Repository Dependabot Security Updates Automatic security update PRs Enable - Enable for automatic remediation About Dependabot security updates
Repository Dependabot Version Updates Automatic dependency update PRs Enable - Keep dependencies current About Dependabot version updates
Repository Secret Scanning Detects committed secrets Enable - Enable secret scanning About secret scanning
Repository Push Protection Blocks commits containing secrets Enable - Prevent secret exposure at commit time About push protection
Repository Secret Scanning Validity Checks Validates if detected secrets are active Enable - Prioritize active secrets for remediation Enabling validity checks
Repository Code Scanning (CodeQL) Static analysis security scanning Enable default setup - Enable CodeQL for supported languages About code scanning
Repository Private Vulnerability Reporting Allows private security reports Enable - Enable for responsible disclosure About private vulnerability reporting

Repository Configuration

Level Policy/Setting Description Recommended Setting Reference
Repository CODEOWNERS File Defines code ownership Configure - Create .github/CODEOWNERS for critical paths About code owners
Repository Security Policy Documents security practices Create - Add SECURITY.md with vulnerability reporting instructions Adding a security policy
Repository Repository Visibility Public, private, or internal Internal/Private - Use internal for innersource; avoid public for proprietary code Setting repository visibility
Repository Merge Strategies Allowed merge methods Squash or Rebase - Maintain clean commit history Managing repository settings
Repository Auto-Delete Head Branches Deletes branches after merge Enable - Keep repository clean Managing the automatic deletion of branches
Repository Commit Signoff Requires DCO sign-off Enable (if required) - For compliance/licensing requirements Managing the commit signoff policy

GitHub Actions (Repository Level)

Level Policy/Setting Description Recommended Setting Reference
Repository Actions Permissions Controls workflow execution Restrict - Follow organization policy; use reusable workflows Managing GitHub Actions settings
Repository Workflow Permissions GITHUB_TOKEN permissions Read-only - Request specific permissions in workflow Modifying the permissions for the GITHUB_TOKEN
Repository Require Approval for Fork PRs Requires approval before running workflows Enable - Prevent malicious workflow execution from forks Managing GitHub Actions settings

Quick Reference: Security Priority Matrix

Priority Setting Category Key Actions
Critical Identity & Access Enable EMU/SAML SSO, Require 2FA (secure methods), Configure IP allow list
Critical Secrets Protection Enable secret scanning + push protection, Enable AI detection for generic secrets, Define custom patterns
Critical Code Protection Enable rulesets with required reviews, block force pushes, require status checks
High Supply Chain Enable Dependabot alerts/updates, dependency review in workflows
High Code Quality Enable CodeQL scanning, Copilot Autofix, require code scanning results in rulesets
High Actions Security Restrict actions to verified sources, read-only GITHUB_TOKEN, require approval for fork PRs
High Access Control Set base permissions to None/Read, restrict repository creation/visibility changes
Medium PAT Management Enforce PAT lifetime limits, require approval for fine-grained PATs, restrict classic PATs
Medium Audit & Compliance Enable audit log streaming, verify domains
Medium Repository Hygiene Enforce signed commits (where feasible), configure CODEOWNERS
Medium Copilot Governance Block suggestions matching public code, control Copilot feature availability

References

Official GitHub Documentation

  1. Enterprise Policies

  2. Organization Settings

  3. Repository Settings

  4. Security Features

  5. Identity and Access Management

GitHub Well-Architected Framework

  1. GitHub Well-Architected Framework
  2. Application Security Pillar
  3. Governance Pillar
  4. GitHub Enterprise Policies & Best Practices
  5. Rulesets Best Practices
  6. Custom Properties Best Practices

GitHub Resources and Blog

  1. Configure GitHub Enterprise Cloud enterprise settings and policies
  2. Best practices for organizations and teams using GitHub Enterprise Cloud
  3. Best practices for enterprises
  4. The Book on GitHub Enterprise Cloud Adoption

Community Resources

  1. Locking Down GitHub Enterprise: A Security-First Approach

Version History

Version Date Changes
1.0 January 2026 Initial document creation
1.1 January 20, 2026 Accuracy review: Added EMU-specific clarifications, updated policy notes for 2FA, workflow permissions, PAT lifetimes, fork restrictions, deploy keys, Copilot Autofix, AI detection, and signed commits

Note: This document should be reviewed and updated regularly as GitHub releases new features and security capabilities. Always refer to the official GitHub documentation for the most current information.