GitHub rulesets define how different people are allowed to interact with specific branches and tags. 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.

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

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/**
  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

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

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. Conversely, ruleset files which are added to this directory (on the default branch) are automatically imported whenever this directory is updated.

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.

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

GitHub Graph is a tool to duplicate files across multiple GitHub repositories.