GitHub Safe-Settings

Safe-settings operates as a service that listens for GitHub webhook events, runs as a scheduled job, or is triggered via GitHub Actions. It ensures repository settings remain consistent with your configuration files.

Key Webhook Events

• push: Triggered when .github/settings.yml, .github/repos/*.yml, or .github/suborgs/*.yml are modified in the default branch of the admin repo. Settings are applied using a hierarchy: Repo settings > Sub-org settings > Org settings.
• repository.created: Automatically applies the hierarchy of settings to new repositories.
• branch_protection_rule & repository_ruleset: If modified via the GitHub UI, Safe-settings will sync the settings to revert unauthorized changes.
• repository.edited: Syncs settings if properties like the default branch or topics change.
• repository.renamed: By default, it ignores renames. If BLOCK_REPO_RENAME_BY_HUMAN=true, it reverts renames unless performed by a bot. If a bot renames a repo, it attempts to copy <old-repo>.yml to <new-repo>.yml.
• pull_request.opened/reopened & check_suite.requested: If settings are changed in a non-default branch, Safe-settings runs in nop mode and updates the PR with a dry-run status report.
• member/team events: Syncs settings to prevent unauthorized permission changes.
• custom_property_values: Applies sub-org configurations if a repository's custom properties match a defined sub-org scope.

When using GitHub Rulesets, status checks defined at the Organization, Sub-organization, and Repository levels are independent. However, there are specific constraints and behaviors regarding how Safe-Settings manages them:

Deployment Constraints

• Duplicate Definition Error: You cannot define the same required_status_checks at both a Sub-org level and a Repository level for the same repository. If you attempt to deploy such a configuration, the repository-level deployment will fail with the error: required_status_checks can't be defined twice in both sub-org and repo level.

Behavior with Custom (Externally Defined) Checks

Safe-Settings manages the reconciliation of status checks based on where custom checks are introduced:

1. No Custom Checks: If no custom checks are defined in your configuration, Safe-Settings will revert any manual changes made via the GitHub UI back to the safe settings at the Org and Sub-org levels.
2. Custom Checks at Org/Sub-org Level: If you use {{EXTERNALLY_DEFINED}} at the Org or Sub-org level, Safe-Settings will retain those custom checks when you update via the GitHub UI. However, if a repository (e.g., Repo2) has its own specific status checks defined in the configuration, Safe-Settings will revert those repository-level checks to the safe settings if you try to add custom ones via the UI.
3. Custom Checks at Repo Level: If custom checks are defined at the Repository level, Safe-Settings will retain them when updated via the GitHub UI, but it will revert the Org and Sub-org status checks to the safe settings if they are modified manually.

Branch protection rules follow a hierarchical inheritance model where checks from higher levels (Org/Sub-org) flow down to repositories. Safe-Settings manages these as follows:

Inheritance Logic

• Standard Inheritance: By default, a repository inherits all status checks defined at the Organization and Sub-organization levels. For example, if main is protected at the Org level with Org Check and at the Sub-org level with Sub-org Check, a repository (Repo1) will automatically have both applied.

Managing Custom Checks

Safe-Settings allows for 'custom' (externally defined) checks, but their placement affects how the hierarchy is enforced:

• Custom Checks at Org or Sub-org Level: If you define custom checks at these higher levels, Safe-Settings will allow those custom checks to be retained when modified via the GitHub UI. However, during a new deployment of rules, the inherited checks from higher levels may be cleared ([]) at the repository level to ensure the higher-level configuration is the source of truth.
• Custom Checks at Repo Level: If you define custom checks at the Repository level, Safe-Settings will retain them when updated via the GitHub UI. However, it will revert the status checks at the Org and Sub-org levels to the safe settings if they are manually changed, and it will not automatically inherit the higher-level checks into that specific repository's protection rule if the repository-level rule is being managed as a custom set.

The AWS Lambda deployment uses a dual Lambda function architecture to separate real-time event handling from background maintenance tasks. Both functions are powered by the same Docker image but are configured with different entry points (commands) via the image-config parameter.

• safe-settings-lambda (Webhook Handler): Triggered by GitHub webhooks via a Function URL. It processes real-time events using the safe-settings-handler.webhooks command.
• safe-settings-scheduler (Scheduler Handler): Triggered by Amazon EventBridge on a schedule. It performs periodic synchronization tasks using the safe-settings-handler.scheduler command.

Inside the code, the safe-settings-handler.js uses smart routing logic to determine which handler to execute based on the incoming event source.

// EventBridge scheduled events → Scheduler handler
if (event.source === 'aws.events' || event.sync === true) {
  return await schedulerHandler(event, context)
}

// GitHub webhooks → Webhook handler  
return await webhookHandler(event, context)

You can allow status checks to be managed outside of Safe-settings (e.g., by other CI tools) while still using Safe-settings for branch protection or rulesets. Use the {{EXTERNALLY_DEFINED}} placeholder in the contexts or required_status_checks field.

Usage

• Branch Protection: Specify {{EXTERNALLY_DEFINED}} under branches.protection.required_status_checks.contexts.
• Rulesets: Specify {{EXTERNALLY_DEFINED}} under rulesets.rules.parameters.required_status_checks.

Important Behaviors

• Merging: Contexts defined at the org level are merged into sub-org and repo levels. Rules from sub-orgs are merged into repo-level rules if they share the same name.
• Deployment: When first deployed with {{EXTERNALLY_DEFINED}}, the rule is created with no status checks. Existing rules in GitHub remain unchanged.
• ⚠️ Warning: If you remove {{EXTERNALLY_DEFINED}} from a configuration, Safe-settings will revert the GitHub settings to match exactly what is defined in your YAML files, potentially overwriting manual UI changes.

# Branch protection example
branches:
  - name: main
    protection:
      ...
      required_status_checks:
        contexts:
          - "{{EXTERNALLY_DEFINED}}"

# Ruleset example
rulesets:
  - name: Status Checks
    ...
    rules:
      - type: required_status_checks
        parameters:
          required_status_checks:
            - context: "{{EXTERNALLY_DEFINED}}"