GitHub Settings Sync

A command-line tool to synchronize repository settings across a GitHub organization.

Features

Synchronize repository settings across all repositories in an organization
Manage repository collaborators and their roles
Configure branch protection rules
Synchronize file contents from local files to repositories
Customizable settings via JSON file
Filter repositories by name pattern, labels, or language
Supports pagination for organizations with many repositories
Detailed logging of operations
Support for GitHub Enterprise via custom base URL

Prerequisites

Node.js 18 or higher
GitHub Personal Access Token with repo and admin:org scopes

Global Installation

npm install -g github-settings-sync

Local Installation

Clone this repository
Install dependencies:
```
npm install
```
Install the package globally (optional):
```
npm install -g .
```

Usage

Run the tool using the global command:

github-settings-sync --org my-org --settings settings.json [options]

Command Line Arguments

Required Arguments:

-o, --org <organization>: GitHub organization name
-s, --settings <path>: Path to JSON file with repository settings

Authentication Options:

-t, --token <token>: GitHub Personal Access Token (overrides GITHUB_TOKEN env var)
-u, --base-url <url>: GitHub API base URL (for GitHub Enterprise)

Filter Options:

-n, --name-pattern <pattern>: Regular expression pattern to match repository names to include
-l, --label <label>: Only process repositories that have this label
-lang, --language <language>: Only process repositories with this primary language

Examples:

# Basic usage with environment variables
github-settings-sync --org my-org --settings settings.json

# Using CLI token instead of environment variable
github-settings-sync --org my-org --settings settings.json --token ghp_xxxxxxxxxxxx

# Using GitHub Enterprise
github-settings-sync --org my-org --settings settings.json --base-url https://github.enterprise.com/api/v3

# Only process repositories with names containing 'api' or 'service'
github-settings-sync --org my-org --settings settings.json --name-pattern "api|service"

# Only process repositories with the 'active' label
github-settings-sync --org my-org --settings settings.json --label active

# Only process Python repositories
github-settings-sync --org my-org --settings settings.json --language python

# Combine multiple filters (repositories must match ALL specified filters)
github-settings-sync --org my-org --settings settings.json --name-pattern "api" --language python

Note: If no filters are specified, all repositories will be processed. When multiple filters are specified, repositories must match ALL specified filters to be processed.

Settings File

Create a JSON file with your desired repository settings. Here's an example of the configuration format:

{
  "repository": {
    "has_issues": true,
    "has_wiki": false,
    "has_projects": true,
    "allow_squash_merge": true,
    "allow_merge_commit": false,
    "allow_rebase_merge": true,
    "delete_branch_on_merge": true,
    "allow_auto_merge": true,
    "allow_update_branch": true
  },
  "collaborators": [
    {
      "username": "user1",
      "role": "admin"
    },
    {
      "username": "user2",
      "role": "write"
    },
    {
      "username": "user3",
      "role": "read"
    }
  ],
  "branch_protection": {
    "main": {
      "enforce_admins": true,
      "required_status_checks": {
        "strict": true,
        "contexts": ["ci/build", "ci/test"]
      },
      "required_pull_request_reviews": {
        "required_approving_review_count": 2,
        "dismiss_stale_reviews": true,
        "require_code_owner_reviews": true
      },
      "allow_force_pushes": false,
      "allow_deletions": false
    },
    "develop": {
      "enforce_admins": false,
      "required_status_checks": {
        "strict": true,
        "contexts": ["ci/build"]
      },
      "required_pull_request_reviews": {
        "required_approving_review_count": 1,
        "dismiss_stale_reviews": true
      },
      "allow_force_pushes": false,
      "allow_deletions": false
    }
  },
  "files": [
    {
      "path": ".gitignore",
      "localPath": "./templates/.gitignore"
    },
    {
      "path": "CONTRIBUTING.md",
      "localPath": "./templates/CONTRIBUTING.md"
    }
  ]
}

Repository Settings

The repository object contains all repository-level settings:

has_issues: Enable/disable issues
has_wiki: Enable/disable wiki
has_projects: Enable/disable projects
allow_squash_merge: Enable/disable squash merges
allow_merge_commit: Enable/disable merge commits
allow_rebase_merge: Enable/disable rebase merges
delete_branch_on_merge: Enable/disable automatic branch deletion
allow_auto_merge: Enable/disable auto-merge
allow_update_branch: Enable/disable branch updates

Collaborator Management

The collaborators array can specify users and their roles. Available roles are:

admin: Full repository access
maintain: Repository maintenance access
write: Push access
triage: Issue and PR triage access
read: Read-only access

The script will:

Add new collaborators with specified roles
Update roles for existing collaborators if they've changed
Preserve existing collaborators not in the list

Note: The script will not remove any existing collaborators. It only adds new ones and updates roles for existing ones.

Branch Protection Rules

The branch_protection object maps branch names to their protection rules. Each branch can have the following settings:

enforce_admins: Whether to enforce restrictions for administrators
required_status_checks: Status check requirements
- strict: Require branches to be up to date before merging
- contexts: Array of required status check contexts
required_pull_request_reviews: Pull request review requirements
- required_approving_review_count: Number of required approving reviews
- dismiss_stale_reviews: Dismiss stale pull request approvals
- require_code_owner_reviews: Require review from Code Owners
allow_force_pushes: Allow force pushes to the branch
allow_deletions: Allow deletion of the branch

Example:

{
  "branch_protection": {
    "main": {
      "enforce_admins": true,
      "required_status_checks": {
        "strict": true,
        "contexts": ["ci/build"]
      },
      "required_pull_request_reviews": {
        "required_approving_review_count": 2,
        "dismiss_stale_reviews": true
      },
      "allow_force_pushes": false
    }
  }
}

The script will:

Apply protection rules to each specified branch
Update existing protection rules if they differ from the configuration
Log success or failure for each branch protection update

File Synchronization

The files array specifies files to be synchronized from local paths to repositories. Each file configuration requires:

path: Path in the repository where the file should be (e.g., .gitignore, CONTRIBUTING.md)
localPath: Path to the local file that contains the desired content

Example:

{
  "files": [
    {
      "path": ".gitignore",
      "localPath": "./templates/.gitignore"
    },
    {
      "path": "docs/CONTRIBUTING.md",
      "localPath": "./templates/CONTRIBUTING.md"
    }
  ]
}

The script will:

Read the content of each local file
Check if the file exists in the repository
Create the file if it doesn't exist
Update the file if its content differs from the local file
Skip the file if its content matches the local file
Log success or failure for each file operation

This is useful for maintaining consistent files across repositories, such as:

.gitignore files
CONTRIBUTING.md guidelines
README.md templates
Configuration files
License files

Error Handling

The script will:

Log errors for individual repository updates but continue processing other repositories
Exit with an error code if there are critical failures (e.g., authentication issues, missing settings)
Provide detailed error messages for troubleshooting
Show a summary of processed and skipped repositories

License

MIT