Configuration

The bot is configured via a YAML configuration file. The configuration file is stored in a GitHub repository and is retrieved by the bot at startup. The configuration file can be updated at any time and the changes will take effect immediately.

Customise the example configuration below to match your organisation's needs and create a private repository to store it. Make a note of the repository URL as it will be required when deploying Governor. For example, if the repository is https://github.com/example/governor and the file is located at config.yaml, the ConfigUrl parameter would be https://github.com/example/governor/config.yaml.

# Reusable email groups for notifications.
groups:
  system_maintainers:
    - example@domain.com
  organisation_maintainers:
    - example@domain.com

# System settings (required).
system:
  maintainers: system_maintainers # Group to notify on system errors (required).
  notifications:
    sender: "governor@mail.domain.com"

# Organisations to manage. Events from unlisted organisations are ignored.
organisations:
  example:
    configuration: default # Configuration to apply (required).
    maintainers: organisation_maintainers # Group to notify on org errors (required).

# GitHub repository rulesets to apply. Referenced by name in configurations.
repository_rulesets:
  default:
    name: default-branch
    target: branch
    enforcement: active
    conditions:
      ref_name:
        exclude: []
        include:
          - "~DEFAULT_BRANCH"
    bypass_actors: []
    rules:
      deletion: {}
      non_fast_forward: {}
      required_linear_history: {}
      pull_request:
        required_approving_review_count: 0 # Set to 1+ for team projects.
        dismiss_stale_reviews_on_push: true
        require_code_owner_review: false
        require_last_push_approval: false # Set to true for team projects.
        required_review_thread_resolution: true
        allowed_merge_methods:
          - squash
          - rebase

# Pull request and repository rules. Applied to organisations by name.
configurations:
  default:
    # Allowed commit types for conventional commits format.
    # Default: feat, fix, refactor, perf, test, style, chore, docs, revert.
    allowed_conventional_commit_types:
      - feat
      - fix
      - refactor
      - perf
      - test
      - style
      - chore
      - docs
      - ci
      - revert
    pull_request:
      notes: | # Optional notes added to approved PRs.
        ## Peer Review Guidelines

        When reviewing changes, evaluate them against these core principles:

         * KISS (Keep It Simple Stupid)
         * Fail Fast
         * Single Responsibility
         * Strict Error Boundaries
         * Secure by Design
         * Zero Trust

        ### Review Checklist (Non-Exhaustive)

        **Code Quality & Hygiene**

         * Failing or missing unit tests
         * Outdated, vulnerable, or deprecated dependencies
         * Unused or duplicate code
         * Misleading or unclear naming

        **Implementation & Security**

         * Unnecessary complexity
         * Unhandled errors or poor logging
         * Logging of sensitive data
         * Missing input validation
         * Insecure patterns (e.g., string-based object creation, unsafe query construction, insecure deserialization)
      # Limits per commit type. Use -1 or omit for no limit. Only applies to conventional commits.
      commit_type_limits:
        feat: 1
      title:
        format: "conventional_commits"
      commits:
        max: 10
        allow_identical_messages: false
        # Email address domains allowed for commits.
        allowed_email_domains:
          - example.com
          - github.com
      # Forbidden content is a list of patterns to match against the file names
      # in the commits of a pull request. If a match is found, the pull request is
      # rejected. Use this feature to prevent accidental exposure of sensitive
      # information in the repository.
      forbidden_content:
        - pattern: "^.*\\.pfx$"
          message: "PFX file are not allowed in the repository."
        - pattern: "^.*\\.key$"
          message: "Private key files are not allowed in the repository."
        - pattern: "^.*\\.pem$"
          message: "PEM files are not allowed in the repository."
        - pattern: "^.*\\.crt$"
          message: "Certificate files are not allowed in the repository."
        - pattern: "^.*\\.csr$"
          message: "Certificate signing request files are not allowed in the repository."
        - pattern: "^(.*/)?node_modules/.*$"
          message: "node_modules directory is not allowed in the repository."

    repository:
      name:
        pattern: "^[a-zA-Z0-9_]{1,64}-(app|service|library|iac)-[a-zA-Z][a-zA-Z0-9_]*(?:-(.*))?$" # Regex for valid names.
        delete_non_matching: true # Delete repos that don't match the pattern.
        exclude: # Repos excluded from name validation.
          - ".stronghold"
      force_private: true
      disable_merge_commits: true
      delete_head_branch_on_merge: true
      disable_forking: true
      repository_rulesets:
        - default
      dependabot:
        enabled: true # Enable alerts and notify maintainers for matching severities.
        enabled_pull_requests: false
        exclude_projects: [] # Regex patterns to skip Dependabot config.
        severities: # Severities to report: critical, high, medium, low.
          - critical
          - high