Skip to main content

​
Welcome to Safe Settings

Safe Settings is a GitHub App that enables policy-as-code management for your GitHub organization. Instead of manually configuring each repository, you define policies centrally and Safe Settings automatically applies them across your organization.

Quick Start

Get Safe Settings deployed and running in under 10 minutes

How It Works

Understand the architecture, webhooks, and configuration hierarchy

Configuration Reference

Comprehensive guide to all available settings and options

Deployment Options

Deploy to AWS Lambda, Docker, Kubernetes, or GitHub Actions

​
What is Safe Settings?

Safe Settings is a Probot-based GitHub App that enforces repository settings as code. All settings are stored in a central admin repository, and Safe Settings automatically syncs these configurations to your repositories when changes are detected.

​
Key features

Centralized Control

Manage all repository settings from a single admin repository

Three-Tier Hierarchy

Organization → Sub-Organization → Repository level configurations

Drift Prevention

Automatically reverts unauthorized manual changes to settings

Pull Request Validation

Dry-run mode validates changes before applying them

Custom Validators

Define custom rules to enforce organizational policies

Scheduled Sync

Periodic reconciliation to prevent configuration drift

​
What can you manage?

Safe Settings supports comprehensive repository and organization configuration:

​
Repository settings

  • Basic settings: Description, homepage, visibility, features (issues, projects, wikis)
  • Branch protections: Required reviews, status checks, enforce admins
  • Repository rulesets: Advanced branch and tag protection rules
  • Teams & collaborators: Access permissions and restrictions
  • Issue labels & milestones: Standardized labels across repositories
  • Custom properties: Metadata for categorizing repositories
  • Environments: Deployment protection rules, required reviewers
  • Autolinks: Reference external resources automatically
  • Variables: Repository and environment variables

​
Organization settings

  • Organization rulesets: Apply protection rules across multiple repositories
  • Custom properties: Define organization-level metadata schemas

​
Configuration hierarchy

Safe Settings uses a three-tier configuration hierarchy that allows you to define settings at different levels of granularity: Precedence order: Repository > Sub-Organization > Organization
Settings at more specific levels override settings from broader levels. For example, a repository-specific configuration overrides both sub-org and org-level settings.

​
Organization level (.github/settings.yml)

Define default settings applied to all repositories in your organization: 
repository:
  private: true
  has_issues: true
  default_branch: main
  delete_branch_on_merge: true

labels:
  - name: bug
    color: CC0000
    description: An issue with the system

branches:
  - name: default
    protection:
      required_pull_request_reviews:
        required_approving_review_count: 1
      enforce_admins: true

​
Sub-organization level (.github/suborgs/*.yml)

Define settings for groups of repositories based on:
  • Repository name patterns: frontend-*, api-*, core-*
  • Team membership: Repositories accessible to specific teams
  • Custom properties: Repositories with specific metadata values
suborgrepos:
  - frontend-app
  - frontend-web
  - frontend-*

suborgteams:
  - frontend-team

repository:
  topics:
    - frontend
    - javascript

branches:
  - name: default
    protection:
      required_pull_request_reviews:
        required_approving_review_count: 2

​
Repository level (.github/repos/<repo-name>.yml)

Define repository-specific overrides: 
repository:
  force_create: true
  template: template_repo
  description: API service for user authentication
  topics:
    - api
    - authentication
    - nodejs

branches:
  - name: default
    protection:
      required_pull_request_reviews:
        required_approving_review_count: 3

​
Why use Safe Settings?

​
Without Safe Settings

  • Manual configuration of each repository
  • Inconsistent settings across repositories
  • No audit trail of changes
  • Difficult to enforce organizational policies
  • Manual drift detection and remediation
  • Risk of unauthorized changes

​
With Safe Settings

  • Automated configuration management
  • Consistent policies across all repositories
  • Git-based audit trail with CODEOWNERS
  • Automated policy enforcement
  • Automatic drift prevention
  • Pull request validation before changes
  • Scheduled reconciliation
Safe Settings is particularly valuable for organizations with:
  • Many repositories (10+): Reduces manual configuration effort exponentially
  • Multiple teams: Delegate policy management using CODEOWNERS
  • Compliance requirements: Enforce security and governance policies automatically
  • High standards: Prevent manual misconfigurations and drift

​
How it works (simplified)

  1. Configure: Define settings in your admin repository’s YAML files
  2. Commit: Push changes to the default branch or create a pull request
  3. Validate: Safe Settings runs in dry-run mode for pull requests
  4. Apply: Settings are automatically applied when merged to default branch
  5. Protect: Safe Settings prevents unauthorized manual changes via webhooks
  6. Reconcile: Scheduled sync ensures configuration stays aligned

Ready to get started?

Follow the quickstart guide to deploy Safe Settings in your organization

Want to learn more?

Dive deeper into Safe Settings’ architecture and capabilities

​
Community and support

Safe Settings is open source and maintained by GitHub:
  • Repository: github/safe-settings
  • License: ISC
  • Built with: Probot framework
  • Node.js: Requires Node.js 18.0.0 or later (22.0.0+ recommended)

Build docs developers (and LLMs) love

Get started for freeTalk to us