diff --git a/README.md b/README.md
index 402c3aa9..6ee9c08a 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,19 @@
+> [!IMPORTANT]
+> As of `v3` this action has been superceded by `gradle/actions/setup-gradle`.
+> Any workflow that uses `gradle/gradle-build-action@v3` will transparently delegate to `gradle/actions/setup-gradle@v3`.
+>
+> Users are encouraged to update their workflows, replacing:
+> ```
+> uses: gradle/gradle-build-action@v3
+> ```
+>
+> with
+> ```
+> uses: gradle/actions/setup-gradle@v3
+> ```
+>
+> See the [setup-gradle documentation](https://github.com/gradle/actions/tree/main/setup-gradle) for up-to-date documentation for `gradle/actons/setup-gradle`. 
+
 # Execute Gradle builds in GitHub Actions workflows
 
 This GitHub Action can be used to configure Gradle and optionally execute a Gradle build on any platform supported by GitHub Actions.