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.

[rozyczko]

2. Ruleset: develop branch protection

Add 2 PR reviewers (since 1 is always GH labels)

4. Ruleset: release tags protection

We do need to be able to delete tags (unless it's @henrikjacobsenfys 's repos)

[rozyczko]

Needs merging into #12

[AndrewSazonov]

Updated description:

To keep repositories consistent and prevent accidental history rewrites, we apply standardized branch protection rules to the following branches:

1. master

Production branch. Changes must go through pull requests and preserve full merge history.

• Restrict deletions
• Block force pushes
• Require pull request before merging
  • Allowed merge methods: Merge only

Configuration:
https://github.com/easyscience/templates/blob/master/template/.github/rulesets/master.json

2. develop

Main integration branch for feature work. Must remain clean and linear.

• Restrict deletions
• Block force pushes
• Require pull request before merging
  • Allowed merge methods: Squash only
• Bypass: easyscience GitHub App
  (required for automated master → develop backmerge)

Configuration:
https://github.com/easyscience/templates/blob/master/template/.github/rulesets/develop.json

3. gh-pages

Reserved exclusively for generated documentation. Updated automatically by CI. No manual changes.

• Restrict deletions
• Block force pushes

Configuration:
https://github.com/easyscience/templates/blob/master/template/.github/rulesets/gh-pages.json

---

GitHub rulesets are configured per repository:
https://github.com/easyscience/REPO/settings/rules

Application of rules is automated via Pixi as described in:
https://github.com/easyscience/templates/blob/master/README.md

[AndrewSazonov]

Here is the updated diagram for #12. We realized that the hotfix strategy was missing in the previous version, so it is now included.

The diagram is now Mermaid-based, which is natively supported in GitHub Markdown. This makes it easier to maintain and update in the future.

---
config:
  logLevel: 'debug'
  theme: 'base'
  themeVariables:
    git0: '#a4c8ff'   # master
    git1: '#ff857c'   # hotfix
    git2: '#adc7aa'   # develop
    git3: '#ffb466'   # feature/F1
    git4: '#ed9f70'   # feature/F2
    git5: '#ffde7c'   # feature/F3
    commitLabelColor: '#000'
    commitLabelBackground: '#ccc'
  gitGraph:
    diagramPadding: 40
    showBranches: true
    showCommitLabel: true
    mainBranchName: 'master'
---

gitGraph
  commit id: "Initial commit"

  %% Develop
  branch develop order: 2
  checkout develop
  commit id: "Develop: initial commit"

  %% Feature F1
  branch "feature/F1" order: 3
  checkout "feature/F1"
  commit id: "F1: commit 1"
  commit id: "F1: commit 2"
  checkout develop
  merge "feature/F1" id: "F1: PR (squash)"

  %% Feature F2a
  branch "feature/F2" order: 4

  %% Feature F3a
  branch "feature/F3" order: 5
  checkout "feature/F3"
  commit id: "F3: commit 1"

  %% Feature F2b
  checkout "feature/F2"
  commit id: "F2: commit 1"
  commit id: "F2: commit 2"
  checkout develop
  merge "feature/F2" id: "F2: PR (squash)"

  %% Feature F3b
  checkout "feature/F3"
  merge develop id: "F3: sync from develop"
  commit id: "F3: commit 2"
  checkout develop
  merge "feature/F3" id: "F3: PR (squash)"

  %% Release 1.0.0
  checkout master
  merge develop id: "Release 1.0.0: PR (merge)" tag: "v1.0.0"

  %% Backmerge after 1.0.0
  checkout develop
  merge master id: "Backmerge after v1.0.0"

  %% Hotfix
  checkout master
  branch hotfix order: 1
  checkout hotfix
  commit id: "Hotfix: commit 1"

  %% Release 1.0.1
  checkout master
  merge hotfix id: "Release 1.0.1: PR (merge)" tag: "v1.0.1"

  %% Backmerge after 1.0.1
  checkout develop
  merge master id: "Backmerge after v1.0.1"

Loading