⚖️ GitHub Rules

A tool to define GitHub rulesets and settings in-source.

🚨 Problem

GitHub rulesets define how different people are allowed to interact with specific branches and tags, and repository settings control features such as merge strategies, PR behaviour, and wikis. An important limitation, however, is that they can only be configured in the settings tab on GitHub, and not from the repository's source code. This can limit scalability in cases where the same settings must be manually configured across multiple projects. It is possible to export/import rules in JSON format, but this isn't as seemless as having the rules defined directly in the repository itself.

💡 Solution

GitHub Rules instead supports a workflow whereby all rulesets and settings are defined exclusively in-source. Every *.json file in .github/rulesets is automatically applied as a ruleset, and .github/settings.json defines repository-level settings. Both are kept in sync by a GitHub workflow watching for changes, and the link is bidirectional; manual changes to the configuration can also be exported back to source.

⬇️ Installation

1. Add the ruleset import and export workflows

Create two new workflow definitions in .github/workflows: import-rulesets.yml and export-rulesets.yml:

# import-rulesets.yml

name: Import Rulesets
on:
  push:
    paths:
      - .github/rulesets/**
      - .github/settings.json
  workflow_dispatch:

jobs:
  import:
    uses: SgtSwagrid/github-rules/.github/workflows/import-rulesets.yml@main
    secrets: inherit

# export-rulesets.yml

name: Export Rulesets
on:
  workflow_dispatch:

jobs:
  export:
    uses: SgtSwagrid/github-rules/.github/workflows/export-rulesets.yml@main
    secrets: inherit

2. Create a Personal Access Token

In order for GitHub Actions to automatically manage rulesets and create pull requests, you'll need a Personal Access Token (PAT) with at least the following permissions in your repository:

• Contents with access Read and write.
• Pull requests with access Read and write.
• Administration with access Read and write.

You can manage your tokens here. Once created, add it as a repository secret named GH_TOKEN under:

Settings → Secrets and variables → Actions → New repository secret

🔨 Usage

There are two separate kinds of configuration, rulesets and settings. Every *.json file in .github/rulesets is automatically applied as a ruleset, and .github/settings.json defines repository-level settings.

Rulesets

Rulesets can be manually created under:

Settings → Rules → Rulesets

From the Actions tab on GitHub, you can run the Export Rulesets workflow to export your rulesets to .github/rulesets and your settings to .github/settings.json. Conversely, changes to these files on the default branch are automatically imported.

Settings

.github/settings.json supports the following fields (all optional):

Field	Type	Description
allow_squash_merge	boolean	Allow squash-merging pull requests.
allow_merge_commit	boolean	Allow merging pull requests with a merge commit.
allow_rebase_merge	boolean	Allow rebase-merging pull requests.
allow_auto_merge	boolean	Allow auto-merge on pull requests.
allow_update_branch	boolean	Show an "Update branch" button on pull requests.
delete_branch_on_merge	boolean	Automatically delete head branches after a pull request is merged.
web_commit_signoff_required	boolean	Require contributors to sign off on commits made via the web editor.
squash_merge_commit_title	"PR_TITLE" | "COMMIT_OR_PR_TITLE"	Default title for squash merge commits.
squash_merge_commit_message	"PR_BODY" | "COMMIT_MESSAGES" | "BLANK"	Default message for squash merge commits.
merge_commit_title	"PR_TITLE" | "MERGE_MESSAGE"	Default title for merge commits.
merge_commit_message	"PR_BODY" | "PR_TITLE" | "BLANK"	Default message for merge commits.
actions_enabled	boolean	Enable GitHub Actions for the repository.
actions_allowed	"all" | "local_only" | "selected"	Which actions are permitted to run.
actions_default_workflow_permissions	"read" | "write"	Default permissions granted to the GITHUB_TOKEN.
actions_can_approve_pull_request_reviews	boolean	Allow GitHub Actions to approve pull requests.

New repositories

Imports run before GH_TOKEN is added will fail, in which case you may need to run Import Rulesets manually once to load the initial state.

🚩 Limitations

The synchronisation is only automatic in a single direction. Direct changes to your repository's configuration on GitHub aren't reflected in .github/rulesets or .github/settings.json until you manually run the Export Rulesets workflow. This is because configuration changes can't serve as a workflow trigger. Pushes to these files on the default branch in the interim will cause any manual changes to be reverted.

👁️ See also

• See GitHub Graph for a similar a tool to duplicate files across multiple GitHub repositories.
• This project is configured by GitHub Config, using the above.