From 31c33f52676855836430b9fe46f431454146f404 Mon Sep 17 00:00:00 2001
From: Vasilii Iakliushin <viakliushin@gitlab.com>
Date: Thu, 6 Mar 2025 08:33:17 +0100
Subject: [PATCH] Document changes to `List repository tree` REST API response
 code

Contributes to https://gitlab.com/gitlab-org/gitlab/-/issues/514756

Add a deprecation notice
---
 .../17-7-list-endpoint-response-code.yml      | 13 ++++++++++++
 doc/update/deprecations.md                    | 20 +++++++++++++++++++
 2 files changed, 33 insertions(+)
 create mode 100644 data/deprecations/17-7-list-endpoint-response-code.yml

diff --git a/data/deprecations/17-7-list-endpoint-response-code.yml b/data/deprecations/17-7-list-endpoint-response-code.yml
new file mode 100644
index 0000000000000..bfdf4caeba3ea
--- /dev/null
+++ b/data/deprecations/17-7-list-endpoint-response-code.yml
@@ -0,0 +1,13 @@
+- title: 'Error handling for `/repository/tree` REST API endpoint returns `404`'
+  announcement_milestone: '16.5'
+  removal_milestone: '17.7'
+  breaking_change: true
+  reporter: phikai
+  stage: Create
+  issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/420865
+  body: |
+    In GitLab 17.7, the error handling behavior for the list repository tree API endpoint, `/projects/:id/repository/tree`, is updated when a requested path is not found. The endpoint now returns a status code `404 Not Found`. Previously, the status code was `200 OK`.
+
+    This change was enabled on GitLab.com in GitLab 16.5, and will be available for self-managed instances in GitLab 17.7.
+
+    If your implementation relies on receiving a `200` status code with an empty array for missing paths, you must update your error handling to handle the new `404` responses.
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md
index 32f417deca02e..1ba5bf0131e3f 100644
--- a/doc/update/deprecations.md
+++ b/doc/update/deprecations.md
@@ -2539,6 +2539,26 @@ another RHEL-compatible operating system.
 
 ## GitLab 17.7
 
+<div class="deprecation breaking-change" data-milestone="17.7">
+
+### Error handling for `/repository/tree` REST API endpoint returns `404`
+
+<div class="deprecation-notes">
+
+- Announced in GitLab <span class="milestone">16.5</span>
+- Removal in GitLab <span class="milestone">17.7</span> ([breaking change](https://docs.gitlab.com/update/terminology/#breaking-change))
+- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/420865).
+
+</div>
+
+In GitLab 17.7, the error handling behavior for the list repository tree API endpoint, `/projects/:id/repository/tree`, is updated when a requested path is not found. The endpoint now returns a status code `404 Not Found`. Previously, the status code was `200 OK`.
+
+This change was enabled on GitLab.com in GitLab 16.5, and will be available for self-managed instances in GitLab 17.7.
+
+If your implementation relies on receiving a `200` status code with an empty array for missing paths, you must update your error handling to handle the new `404` responses.
+
+</div>
+
 <div class="deprecation " data-milestone="17.7">
 
 ### TLS 1.0 and 1.1 no longer supported
-- 
GitLab