All.synchronize gh settings.how to guide

Synchronize GitHub repository settings

• TODO(sandeep): Update the script path references once the dockerized executable is implemented

Overview

• The dockerized_sync_gh_repo_settings.py script helps to export and synchronize GitHub repository settings and branch protection rules through a settings manifest file

• The script supports two operations:

  • export: write current repository settings to a YAML file
  • sync: apply the settings defined in a YAML file to a repository

• The script uses PyGithub library to interact with the GitHub API

• The script is a dockerized executable (i.e., runs in a Docker container to ensure that all the dependencies are verified, e.g., PyGitHub)

• Every time you run sync the script saves a backup of the current settings so you can roll back if needed

  • The settings are backed up in the current working directory

Prerequisites

GitHub token

• You need a GitHub token with appropriate repository management permissions
• Store the token in an environment variable and verify it:

  > echo $GITHUB_TOKEN
  

Settings manifest file structure

• In each repo there are two parts of a configuration we need to set

• The "repository settings" section controls basic repository configuration:

  repository_settings:
      name: "repo-name"
      description: "Repository description"
      homepage: "https://example.com"
      private: true
      archived: false
      has_issues: true
      has_projects: true
      has_wiki: true
      allow_squash_merge: true
      allow_merge_commit: true
      allow_rebase_merge: true
      delete_branch_on_merge: true
      enable_automated_security_fixes: true
      enable_vulnerability_alerts: true
      topics:
          - topic1
          - topic2
  

• The "branch protection" section defines rules for protected branches:

  branch_protection:
      main:
          enforce_admins: true
          allow_force_pushes: false
          allow_deletions: false
          required_status_checks:
              strict: true
              contexts:
                  - "run tests"
          required_pull_request_reviews:
              dismiss_stale_reviews: true
              require_code_owner_reviews: true
              required_approving_review_count: 2
              dismissal_restrictions:
                  users:
                      - "user1"
                  teams:
                      - "team1"
          restrictions:
              users:
                  - "maintainer1"
                  - "maintainer2"
              teams:
                  - "developers"
                  - "admins"
  

• You can use two reference files to help configure your repository:

  1. Common repository settings
  2. Find the file at /dev_scripts_helpers/github/settings/common_repo_settings.yaml
  3. This file contains standard settings that we use across multiple repositories

  4. Start with this file when you want to maintain consistency with other repositories

  5. Template settings

  6. Find the file at /dev_scripts_helpers/github/settings/template_repo_settings.yaml
  7. This template shows all available configuration options with example values
  8. Use this file when you need to create a new settings file from scratch
  9. You can remove any settings parameters you don't need; the script will handle missing entries

How to synchronize repository settings

• View more information about the script's arguments:

  > dockerized_sync_gh_repo_settings.py --help
  

  > dockerized_sync_gh_repo_settings.py export --help
  

  > dockerized_sync_gh_repo_settings.py sync --help
  

• Export repository settings to a YAML file:

  > dockerized_sync_gh_repo_settings.py export \
          --output_file settings.yaml \
          --owner your-org \
          --repo your-repo \
          --token_env_var GITHUB_TOKEN
  

• Synchronize settings from a YAML file to a repository:

  > dockerized_sync_gh_repo_settings.py sync \
          --input_file settings.yaml \
          --owner your-org \
          --repo your-repo \
          --token_env_var GITHUB_TOKEN
  

• Preview changes without applying them by adding --dry_run flag:

  > dockerized_sync_gh_repo_settings.py sync \
          --input_file settings.yaml \
          --owner your-org \
          --repo your-repo \
          --token_env_var GITHUB_TOKEN \
          --dry_run
  

Troubleshooting

1. For permission errors:
2. Verify your GitHub token has sufficient permissions

3. Check your repository admin access

4. If settings are not applied:

5. Run with --dry_run to preview changes
6. Verify the manifest file structure
7. Check all required fields are present