diff --git a/src/content/docs/workflow/actions/delete_head_branch.mdx b/src/content/docs/workflow/actions/delete_head_branch.mdx
index 3b54ab4561..c2fa4451f8 100644
--- a/src/content/docs/workflow/actions/delete_head_branch.mdx
+++ b/src/content/docs/workflow/actions/delete_head_branch.mdx
@@ -5,6 +5,13 @@ description: Delete pull request head branch. Useful to clean pull requests once
 
 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](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches)
+  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.