Skip to main content
Safe Settings uses a powerful three-tier configuration hierarchy to manage repository settings, branch protections, teams, and more across your entire GitHub organization. All configuration files are stored centrally in an admin repository.

​
Configuration Structure

All settings are stored in your admin repository (default: admin) under the .github directory: 
admin/
├── .github/
│   ├── settings.yml          # Organization-wide settings
│   ├── suborgs/              # Sub-organization settings
│   │   ├── frontend-team.yml
│   │   └── backend-team.yml
│   └── repos/                # Repository-specific settings
│       ├── api-service.yml
│       └── web-app.yml

​
Configuration Hierarchy

Settings are applied in a hierarchical manner with the following precedence: Precedence Order: Repository > Sub-Organization > Organization
Repo-level settings override suborg-level settings, which in turn override org-level settings. This allows you to set sensible defaults at the organization level while providing flexibility for specific teams or repositories.

​
How Configuration Merging Works

Safe Settings uses a deep merge algorithm to combine configurations across different levels:
  1. Start with org-level settings - Base configuration from .github/settings.yml
  2. Overlay suborg settings - If the repository belongs to a suborg, merge in suborg-specific settings
  3. Apply repo-specific settings - Finally, apply any repository-specific overrides
For example:
.github/settings.yml
repository:
  private: true
  has_issues: true
  has_wiki: true

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

​
Configurable Settings

Safe Settings allows you to configure the following aspects of your repositories:

Repository Settings

  • Visibility (public/private)
  • Description and homepage
  • Features (issues, projects, wiki)
  • Merge strategies
  • Auto-delete branches

Branch Protection

  • Required reviews
  • Status checks
  • Linear history
  • Admin enforcement
  • Restrictions

Access Control

  • Team permissions
  • Collaborator access
  • Deploy keys

Repository Features

  • Labels
  • Milestones
  • Topics
  • Custom properties
  • Autolinks

Rulesets

  • Org-level rulesets
  • Repo-level rulesets
  • Tag protection
  • Branch patterns

Environments

  • Deployment environments
  • Environment variables
  • Protection rules
  • Required reviewers

​
Configuration File Format

All configuration files use YAML format and follow the same structure. The specific settings available depend on the configuration level:
  • Org-level (.github/settings.yml): Can configure both org-targeted settings (rulesets) and repo-targeted defaults
  • Suborg-level (.github/suborgs/*.yml): Must define which repos belong to the suborg, then can override org settings
  • Repo-level (.github/repos/*.yml): Can override any org or suborg settings for that specific repository
Unlike other repository settings apps, Safe Settings stores all configuration centrally in an admin repository. This provides several benefits:
  • Single source of truth - All policies are in one place
  • Centralized access control - Use CODEOWNERS to control who can approve policy changes
  • Audit trail - All changes are tracked through Git history
  • PR workflow - Changes are validated before being applied
  • Prevents configuration drift - Settings can’t be changed directly in individual repos
Safe Settings uses a clear precedence order: Repository > Sub-Organization > Organization.When the same setting is defined at multiple levels, the most specific level wins. You can also define custom validators to prevent certain overrides (e.g., prevent reducing the number of required reviewers).
Yes! You can set the ADMIN_REPO environment variable to use a different repository name instead of admin. The .github directory can also be customized using CONFIG_PATH, and the org-level settings file can be changed with SETTINGS_FILE_PATH.

​
Next Steps

Configuration Hierarchy

Understand how settings are merged and applied

Org Settings

Configure organization-wide defaults

SubOrg Settings

Create settings for groups of repositories

Repo Settings

Override settings for specific repositories

Build docs developers (and LLMs) love

Get started for freeTalk to us