Align repository settings, branch protection rules and repository collaborators across all your repositories.

Prerequisites

• you should have a Node.js installed on your machine;

  Tip: you may install NVM instead, as it gives you the ability to easily switch between the Node versions.

• your GitHub personal access token;

  Note: you need to have it because Harmonizer is communicating with the GitHub REST API to perform the changes.

Installation

Install via cloning the repository

This is a preferred way, as you would be able to adjust the Harmonizer settings as per your needs in the .harmonizerrc.json file which is the part of this repo.

• clone the repository;
• from the root of the repo run:

  npm run setup

  It will install the package globally on your machine, so you would be able to call the harmonize command from any working directory;
• set up your Harmonizer rules in the .harmonizerrc.json file;

Install via NPM package

You might want to use this way, if you want to use Harmonizer within your CI/CD pipeline and you don't want to clone the repo. This way you would have to create a .harmonizerrc.json configuration file in the working directory where the harmonize command will be called, otherwise the default .harmonizerrc.json configuration will be used.

The package is called github-harmonizer. You may find it on NPM.

• install the Harmonizer globally on your machine:

  npm i -g github-harmonizer

• in your working directory create a .harmonizerrc.json or .harmonizerrc.yaml file and set your Harmonizer rules, otherwise the default .harmonizerrc.json configuration will be used;

Usage

Run the following command and follow the instructions:

harmonize

You can also pass --auth=<github_personal_access_token> and --repo=<owner_name/repo_name> argument values along with harmonize if you want to omit them to be prompted by the Harmonizer CLI. You may also pass a --fetchRemoteConfig flag if you want the .harmonizerrc.json config file to be fetched from the root of the repo which you are harmonizing.

How Harmonizer works?

Harmonizer checks if the working directory, from where the harmonize command was called, has Harmonizer configuration file, it validates this configuration and prompts you for an access token and a repo name which you want to harmonize and applies that configuration to the repo. If the config file was not found, it picks the default one, which is .harmonizerrc.json.

Harmonizer uses a JSON Schema declared in the config.schema.json file. It provides a clear human- and machine- readable documentation for the Harmonizer. It is also used in order to annotate and validate its configuration. It also provides code suggestions and annotations within your IDE if you are using VS Code.

If you prefer to have your configuration in YAML, feel free to replace your .harmonizerrc.json config with a .harmonizerrc.yaml and hold your configuration there instead. The JSON Schema benefits above would also be working for you.

What Harmonizer does?

Harmonizer aligns these repository settings:

• controls visibility of wiki, projects and issues tabs;
• controls visibility of squash merge, merge commits and rebase merge buttons in the pull requests;
• controls the automated delete branch on merge option;

Harmonizer manages repository collaborators:

• adds teams and users to the repo as collaborators;
• grants permissions to the collaborators or updates them;

Harmonizer sets protection rules for the default branch of the repository:

• sets the amount of required PR approvals before merge;
• controls whether to dismiss the stale pull request approvals when new commits are pushed or not;
• controls whether to require review from Code Owners or not;
• controls whether to require branches to be up to date before merging or not;
• controls whether to disallow users with push access to delete the default branch or not;
• controls whether to enable merge commits from being pushed to the default branch or not;
• controls whether to enforce all configured restrictions above for administrators or not;
• controls whether to disallow force pushes for all users with push access or not;
• controls whether to disallow users with push access to delete the default branch or not;

Continuous Deployment

There is a github action that publishes the package to NPM on merge to main, so whenever you are pushing changes to this repo, make sure you bump up the version of the package via the "version" property in the package.json and package-lock.json according to the Semantic Versioning Specification.

TODO

• cover functionality with tests;