ADR Suggestion Branch protection rulesets (master, develop, gh-pages)

[AndrewSazonov]

To keep our repositories consistent and avoid accidental history rewrites, we need a simple and predictable branch-protection setup:

• master
  Should only receive changes via pull requests and preserve full merge history (merge-only PRs).
• develop
  Should stay clean and linear and is the main integration branch for feature work (squash-only PRs).
• gh-pages 

  The gh-pages branch is reserved exclusively for built documentation and must not be modified manually.
  It is updated automatically by the documentation CI workflow.

The branching strategy itself is described in a separate ADR:

https://github.com/orgs/easyscience/discussions/12

Rulesets should be created only after the target branches exist.

GitHub rulesets must be configured per repository:
https://github.com/easyscience/REPOSITORY/settings/rules

Configuration steps

1) Ruleset: master branch protection

• Rulesets → New ruleset → New branch ruleset
• Ruleset name: master branch protection
• Enforcement status: Active
• Branch targeting criteria: Add target → include default branch
• Restrict deletions: ✅
• Require a pull request before merging: ✅
  • Allowed merge methods: Merge only
• Block force pushes: ✅
• Save changes

2) Ruleset: develop branch protection

• Rulesets → New ruleset → New branch ruleset
• Ruleset name: develop branch protection
• Enforcement status: Active
• Branch targeting criteria: Add target → include by pattern → develop
• Restrict deletions: ✅
• Require a pull request before merging: ✅
  • Allowed merge methods: Squash only
• Block force pushes: ✅
• Bypass list:
  • Add bypass → easyscience GitHub App 

    (required for automation such as master → develop backmerge workflows)
• Save changes

3) Ruleset: gh-pages branch protection

• Rulesets → New ruleset → New branch ruleset
• Ruleset name: gh-pages branch protection
• Enforcement status: Active
• Branch targeting criteria: Add target → include by pattern → gh-pages
• Restrict deletions: ✅
• Block force pushes: ✅
• Save changes

4) Ruleset: release tags protection

• Rulesets → New ruleset → New tag ruleset
• Ruleset name: release tags protection
• Enforcement status: Active
• Tag targeting criteria: Add target → include by pattern → v*
• Restrict deletions: ✅
• Block force pushes: ✅
• Save changes

[rozyczko]

It would be awesome to try to automate those tasks, as they are long and tedious.
Can we use copier/templates to enfore those?

Maybe add a post-generation task which configures rulesets on new repo creation?

# copier.yaml
_tasks:
  - "gh api -X POST /easyscience/{{ project_name }}/rulesets --input .github/rulesets/master.json"

with master.json like

{
  "name": "master branch protection",
  "target": "branch",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "include": ["~DEFAULT_BRANCH"],
      "exclude": []
    }
  },
  "rules": [
    {"type": "deletion"},
    {"type": "non_fast_forward"},
    {"type": "pull_request", 
     "parameters": {"allowed_merge_methods": ["merge"],
        "dismiss_stale_reviews_on_push": false,
        "require_code_owner_review": false,
        "require_last_push_approval": false,
        "required_approving_review_count": 0,
        "required_review_thread_resolution": false
      }}
  ]
}

[AndrewSazonov]

That would definitely make things much easier - thanks for the suggestion! To be honest, I wasn’t aware that rulesets could be configured this way via the GitHub API. Automating the setup of the common rulesets sounds like a very nice solution.

One thought on the implementation: I would prefer exposing this explicitly via a few Pixi tasks defined in the pixi.toml template, rather than only applying the default branch protection automatically as a post-generation step. The reason is that different rulesets need to be applied at different moments in the repository lifecycle, depending on the branch:

• the default branch ruleset right after repo creation,
• the develop branch ruleset only after the develop branch is manually created,
• the gh-pages branch ruleset after the branch exists (usually created by mkdocs/mike).

With separate Pixi tasks (e.g. pixi run protect-master, pixi run protect-develop, pixi run protect-gh-pages), users can run the right command at the right time, and the process stays transparent. Then we can keep the templates README very short - just explaining when to run each task instead of documenting all the web-UI steps.