diff --git a/src/content/docs/workflow/actions.mdx b/src/content/docs/workflow/actions.mdx
index e20bed05e2..50a7493e3f 100644
--- a/src/content/docs/workflow/actions.mdx
+++ b/src/content/docs/workflow/actions.mdx
@@ -34,8 +34,8 @@ management.
Comment a pull request.
-
- Delete pull request head branch.
+
+ Deprecated — use GitHub's built-in "Automatically delete head branches" setting instead.
Dismiss previous reviews on a pull request.
diff --git a/src/content/docs/workflow/actions/delete_head_branch.mdx b/src/content/docs/workflow/actions/delete_head_branch.mdx
index 3b54ab4561..eece8b29c3 100644
--- a/src/content/docs/workflow/actions/delete_head_branch.mdx
+++ b/src/content/docs/workflow/actions/delete_head_branch.mdx
@@ -1,10 +1,16 @@
---
-title: Delete Head Branch
-description: Delete pull request head branch. Useful to clean pull requests once closed.
+title: Delete Head Branch (Deprecated)
+description: Delete pull request head branch. Deprecated in favor of GitHub's built-in "Automatically delete head branches" setting.
---
import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable';
+:::danger
+ The `delete_head_branch` action is **deprecated** and will be removed on
+ June 30, 2026. Use GitHub's built-in
+ [automatically delete head branches][gh-auto-delete] setting instead.
+:::
+
The `delete_head_branch` action allows Mergify to automatically delete the head
branch of a pull request once it has been merged. This can be useful for
maintaining a clean repository and reducing clutter from unused branches.
@@ -34,3 +40,5 @@ with "cleanup".
The `delete_head_branch` action is a simple yet powerful tool that can help
maintain the cleanliness and organization of your repository.
+
+[gh-auto-delete]: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches
diff --git a/src/content/docs/workflow/delete-head-branches.mdx b/src/content/docs/workflow/delete-head-branches.mdx
deleted file mode 100644
index 8dbcbee162..0000000000
--- a/src/content/docs/workflow/delete-head-branches.mdx
+++ /dev/null
@@ -1,115 +0,0 @@
----
-title: Delete Head Branches
-description: How to automatically delete head branches.
----
-
-While GitHub offers settings for automatic deletion of merged branches, its
-approach is often a blunt instrument, indiscriminately deleting any merged
-branch. Mergify’s `delete_head_branch` action brings nuance to this process,
-allowing repository maintainers to craft conditions under which branches should
-be deleted after their pull requests are merged. By utilizing Mergify's
-intricate [pull request rules and conditions](/workflow), users can design
-custom branch cleanup strategies that cater to their specific workflow
-requirements.
-
-[GitHub's automatic branch deletion
-documentation](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches)
-provides the basic settings, but for those who require a more nuanced approach,
-Mergify's `delete_head_branch` is the ideal tool.
-
-**GitHub's Default Deletion:** As soon as a pull request branch is merged,
-GitHub will automatically delete it, given the repository setting is enabled.
-This doesn’t account for scenarios where you might want to retain the branch
-for some time or under specific conditions.
-
-**Mergify’s Conditional Deletion:** Using Mergify, one can establish specific
-conditions under which a branch should be deleted post-merge. This can be based
-on labels, types of files changed, the nature of the pull request, and more.
-
-Here are a few example workflows that showcase the flexibility and power of
-Mergify’s `delete_head_branch` action:
-
-## Cleanup On-Demand
-
-Only delete merged branches when the pull request is labeled with "cleanup".
-
-```yaml
-pull_request_rules:
- - name: delete head branch after merge if the label "cleanup" is present
- conditions:
- - merged
- - label = cleanup
- actions:
- delete_head_branch:
-```
-
-## Prevent Deletion for Dependent Branches
-
-Avoid deleting branches that other pull requests depend on, ensuring dependent
-work isn't inadvertently closed.
-
-```yaml
-pull_request_rules:
- - name: delete head branch after merge but not if other PRs depend on it
- conditions:
- - merged
- actions:
- delete_head_branch:
- force: false
-```
-
-## Aggressive Cleanup
-
-In scenarios where you are certain about deleting branches, even if other pull
-requests depend on them:
-
-```yaml
-pull_request_rules:
- - name: always delete head branch after merge
- conditions:
- - merged
- actions:
- delete_head_branch:
- force: true
-```
-
-## Conditional Cleanup Based on File Type
-
-For instance, if documentation-related branches (those that only modify `.md`
-files) need to be deleted immediately post-merge:
-
-```yaml
-pull_request_rules:
- - name: delete doc-related branches post-merge
- conditions:
- - merged
- - "files ~= \.md$"
- actions:
- delete_head_branch:
-```
-
-## Time-based Cleanup
-
-Suppose you want branches to remain for a day post-merge for any potential
-discussions and then get deleted:
-
-```yaml
-pull_request_rules:
- - name: delete branches 24 hours post-merge
- conditions:
- - merged-at < 1 day ago
- actions:
- delete_head_branch:
-```
-
----
-
-The `delete_head_branch` action is an example of how Mergify offers detailed
-control over Git workflows, moving beyond the default settings of platforms
-like GitHub. By understanding the various use-cases and implementing them in
-your repository, you can maintain a cleaner, more organized codebase, and
-ensure that old branches don't clutter your project as it grows.
-
-Remember, the key is in understanding your project's requirements and
-leveraging tools like Mergify to tailor workflows that cater specifically to
-those needs.
diff --git a/src/content/navItems.tsx b/src/content/navItems.tsx
index 5239686b8d..3989d487c0 100644
--- a/src/content/navItems.tsx
+++ b/src/content/navItems.tsx
@@ -212,11 +212,6 @@ const navItems: NavItem[] = [
path: '/workflow/request-reviews',
icon: 'octicon:code-review-16',
},
- {
- title: 'Delete Head Branches',
- path: '/workflow/delete-head-branches',
- icon: 'bi:scissors',
- },
{
title: 'Dismiss Reviews',
path: '/workflow/dismiss-reviews',
@@ -236,7 +231,7 @@ const navItems: NavItem[] = [
{ title: 'Copy', path: '/workflow/actions/copy', icon: 'fa6-solid:share-nodes' },
{ title: 'Comment', path: '/workflow/actions/comment', icon: 'fa-solid:list-alt' },
{
- title: 'Delete Head Branch',
+ title: 'Delete Head Branch (Deprecated)',
path: '/workflow/actions/delete_head_branch',
icon: 'bi:scissors',
},