Configuration Hierarchy

Safe Settings uses a three-tier hierarchical configuration system that allows you to define sensible defaults while providing flexibility for specific teams and repositories.

Precedence Order

Settings are applied with the following precedence:

Repository Settings

Highest priority - Settings in .github/repos/<repo-name>.yml override all other levels

Sub-Organization Settings

Middle priority - Settings in .github/suborgs/*.yml override org-level defaults

Organization Settings

Lowest priority - Settings in .github/settings.yml provide the baseline defaults

The precedence order is: Repository > Sub-Organization > OrganizationAs noted in the codebase: “The precedence order is repository > suborg > org (.github/repos/.yml > .github/suborgs/.yml > .github/settings.yml)“

How Configuration Merging Works

Safe Settings uses a deep merge algorithm implemented in lib/mergeDeep.js. Here’s how it works:

Deep Merge Algorithm

The merge algorithm follows these rules:

Objects are merged recursively - Nested settings are combined at every level
Arrays are merged by name - Array elements with the same name field are merged together
Primitives are overwritten - Simple values from higher precedence levels replace lower ones
Null values are preserved - Setting a value to null explicitly disables it

Merge Example

Let’s see how settings are merged for a repository called api-gateway that belongs to the backend-team suborg:

repository:
  private: true
  has_issues: true
  has_wiki: true
  has_projects: true

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

teams:
  - name: core
    permission: admin

Merge Behavior by Data Type

Objects

Objects are merged recursively. Properties from higher precedence levels are merged into properties from lower levels.

# Org Level
repository:
  private: true
  has_issues: true

# Repo Level
repository:
  has_issues: false  # This overrides
  has_wiki: true     # This is added

# Result
repository:
  private: true      # Kept from org level
  has_issues: false  # Overridden by repo level
  has_wiki: true     # Added from repo level

Arrays

Arrays are merged by matching elements with the same identifying field (usually name, username, or login).

Named Arrays
Simple Arrays

Arrays with elements that have a name field are merged by name:

# Org Level
teams:
  - name: core
    permission: admin
  - name: developers
    permission: push

# SubOrg Level
teams:
  - name: developers
    permission: pull  # This overrides the permission for 'developers'
  - name: backend
    permission: push  # This is added

# Result
teams:
  - name: core
    permission: admin
  - name: developers
    permission: pull   # Overridden
  - name: backend
    permission: push   # Added

Simple arrays (like topics) are concatenated:

# Org Level
repository:
  topics:
    - github
    - automation

# Repo Level
repository:
  topics:
    - api
    - production

# Result
repository:
  topics:
    - github
    - automation
    - api
    - production

Primitives

Primitive values (strings, numbers, booleans) from higher precedence levels completely replace values from lower levels.

# Org Level
repository:
  default_branch: main

# Repo Level  
repository:
  default_branch: master  # This completely replaces the org value

# Result
repository:
  default_branch: master

Configuration Loading Process

When Safe Settings processes a repository, it follows these steps:

Load Organization Config

Read .github/settings.yml from the admin repository. This provides the baseline configuration.

Check SubOrg Membership

Determine if the repository belongs to any sub-organization by:

Matching repository name against suborgrepos patterns
Checking if repository has teams listed in suborgteams
Checking if repository has custom properties matching suborgproperties

Load and Merge SubOrg Config

If the repository belongs to a suborg, load the suborg config and deep merge it with the org config.

Load and Merge Repo Config

Load .github/repos/<repo-name>.yml (if it exists) and deep merge it with the previous result.

Apply Final Configuration

The merged configuration is applied to the repository via GitHub API.

Configuration Scope

Not all settings can be configured at all levels:

Organization-Targeted Settings

Some settings only apply at the organization level:

Rulesets with repository_name conditions (these apply to multiple repositories)

These settings are defined in .github/settings.yml and cannot be overridden at suborg or repo level.

Repository-Targeted Settings

Most settings apply to individual repositories and can be configured at all three levels:

Repository settings (visibility, features, etc.)
Branch protection rules
Teams and collaborators
Labels and milestones
Environments
Custom properties
And more…

rulesets:
  - name: Security Requirements
    target: branch
    enforcement: active
    conditions:
      repository_name:
        include: ["prod-*", "api-*"]
    rules:
      - type: required_signatures

Validation and Override Rules

You can define custom validators in your deployment settings to control which overrides are allowed:

Override Validators
Config Validators

Prevent suborg or repo settings from weakening org-level security:

deployment-settings.yml

overridevalidators:
  - plugin: branches
    error: |
      Branch protection required_approving_review_count cannot be overridden to a lower value
    script: |
      console.log(`baseConfig ${JSON.stringify(baseconfig)}`)  
      console.log(`overrideConfig ${JSON.stringify(overrideconfig)}`)
      if (baseconfig.protection.required_pull_request_reviews.required_approving_review_count && 
          overrideconfig.protection.required_pull_request_reviews.required_approving_review_count) {
        return overrideconfig.protection.required_pull_request_reviews.required_approving_review_count >= 
               baseconfig.protection.required_pull_request_reviews.required_approving_review_count
      }
      return true

Enforce global rules on all configurations:

deployment-settings.yml

configvalidators:
  - plugin: collaborators
    error: |
      Admin role cannot be assigned to collaborators
    script: |
      console.log(`baseConfig ${JSON.stringify(baseconfig)}`)
      return baseconfig.permission != 'admin'

Preventing Configuration Drift

Safe Settings actively prevents configuration drift through webhook events:

When settings are changed directly in GitHub UI, Safe Settings receives an event
It compares the current settings with the configuration in the admin repo
If differences are detected, it syncs the settings back to match the configuration
This ensures your configuration files remain the source of truth

How does Safe Settings detect changes?

Safe Settings listens to webhook events like:

repository.edited - When repository settings are changed
branch_protection_rule - When branch protection is modified
repository_ruleset - When rulesets are changed
member_change_events - When team/collaborator access changes

When these events occur, Safe Settings compares the GitHub settings with your configuration and syncs them back if needed.

Can I temporarily bypass Safe Settings?

No, Safe Settings is designed to enforce your policies consistently. However, you can:

Update your configuration files and create a PR to make changes
Define bypass actors in rulesets who can make emergency changes
Temporarily disable Safe Settings if absolutely necessary (not recommended)

What happens during the sync process?

Safe Settings uses an intelligent comparison algorithm that:

Fetches current settings from GitHub
Compares them with your configuration
Identifies additions, modifications, and deletions
Only makes API calls if there are actual changes
Creates a check run with the results

This ensures Safe Settings is efficient and doesn’t make unnecessary API calls.

Next Steps

Org Settings

Configure organization-wide defaults

SubOrg Settings

Group repositories and apply team-specific policies

Repo Settings

Override settings for individual repositories

Deployment Settings

Configure validators and restrictions

Get Started

Deployment

Configuration

Settings Reference

Advanced

Operations

Precedence Order

How Configuration Merging Works

Deep Merge Algorithm

Merge Example

Merge Behavior by Data Type

Objects

Arrays

Primitives

Configuration Loading Process

Configuration Scope

Organization-Targeted Settings

Repository-Targeted Settings

Validation and Override Rules

Preventing Configuration Drift

Next Steps

Org Settings

SubOrg Settings

Repo Settings

Deployment Settings

Build docs developers (and LLMs) love

Get Started

Deployment

Configuration

Settings Reference

Advanced

Operations

​Precedence Order

​How Configuration Merging Works

​Deep Merge Algorithm

​Merge Example

​Merge Behavior by Data Type

​Objects

​Arrays

​Primitives

​Configuration Loading Process

​Configuration Scope

​Organization-Targeted Settings

​Repository-Targeted Settings

​Validation and Override Rules

​Preventing Configuration Drift

​Next Steps

Org Settings

SubOrg Settings

Repo Settings

Deployment Settings

Build docs developers (and LLMs) love

Precedence Order

How Configuration Merging Works

Deep Merge Algorithm

Merge Example

Merge Behavior by Data Type

Objects

Arrays

Primitives

Configuration Loading Process

Configuration Scope

Organization-Targeted Settings

Repository-Targeted Settings

Validation and Override Rules

Preventing Configuration Drift

Next Steps