diff --git a/data/deprecations/16-8-api-lint-ref-removal.yml b/data/deprecations/16-8-api-lint-ref-removal.yml
new file mode 100644
index 0000000000000000000000000000000000000000..cd99938a60718fb24406329ef48cfbd343556725
--- /dev/null
+++ b/data/deprecations/16-8-api-lint-ref-removal.yml
@@ -0,0 +1,34 @@
+# ----- DELETE EVERYTHING ABOVE THIS LINE -----
+
+- title: "Block usage of ref and sha together in `GET /projects/:id/ci/lint`"
+  # The milestones for the deprecation announcement, and the removal.
+  removal_milestone: "17.0"
+  announcement_milestone: "16.8"
+  # Change breaking_change to false if needed.
+  breaking_change: true
+  # The stage and GitLab username of the person reporting the change,
+  # and a link to the deprecation issue
+  reporter: dhershkovitch
+  stage: verify
+  issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/430322
+  body: |  # (required) Don't change this line.
+    Due to a problem with ambiguity, we've deprecated the use of both `ref` and `sha` in the same API call to `GET /projects/:id/ci/lint`. Make sure your API calls to this endpoint use only `ref` or `sha`, but not both. In GitLab 17.0, using them in the same call will no longer be possible to ensure the correct ref or SHA is linted.
+
+# ==============================
+# OPTIONAL END-OF-SUPPORT FIELDS
+# ==============================
+#
+# If an End of Support period applies:
+# 1) Share this announcement in the `#spt_managers` Support channel in Slack
+# 2) Mention `@gitlab-com/support` in this merge request.
+#
+  # When support for this feature ends, in XX.YY milestone format.
+  end_of_support_milestone:
+  # Array of tiers the feature is currently available to,
+  # like [Free, Silver, Gold, Core, Premium, Ultimate]
+  tiers:
+  # Links to documentation and thumbnail image
+  documentation_url:
+  image_url:
+  # Use the youtube thumbnail URL with the structure of https://img.youtube.com/vi/UNIQUEID/hqdefault.jpg
+  video_url:
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md
index f1a319b863f1efc78d49a3ac0cd87f5f71a50e55..0b939cb60b58ac2dff00034d0cbe09e8075c78f6 100644
--- a/doc/update/deprecations.md
+++ b/doc/update/deprecations.md
@@ -227,6 +227,20 @@ Because Cloud Native Buildpacks do not support automatic testing, the Auto Test
 
 <div class="deprecation breaking-change" data-milestone="17.0">
 
+### Block usage of ref and sha together in `GET /projects/:id/ci/lint`
+
+<div class="deprecation-notes">
+- Announced in GitLab <span class="milestone">16.8</span>
+- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change))
+- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/430322).
+</div>
+
+Due to a problem with ambiguity, we've deprecated the use of both `ref` and `sha` in the same API call to `GET /projects/:id/ci/lint`. Make sure your API calls to this endpoint use only `ref` or `sha`, but not both. In GitLab 17.0, using them in the same call will no longer be possible to ensure the correct ref or SHA is linted.
+
+</div>
+
+<div class="deprecation breaking-change" data-milestone="17.0">
+
 ### Breaking change to the Maven repository group permissions
 
 <div class="deprecation-notes">