diff --git a/files/gitlab-config-template/gitlab.rb.template b/files/gitlab-config-template/gitlab.rb.template
index 8fe3700a88d75cfdecdcf433b0d1accc643cdeb1_ZmlsZXMvZ2l0bGFiLWNvbmZpZy10ZW1wbGF0ZS9naXRsYWIucmIudGVtcGxhdGU=..6c3c5c10cccf988c426fd7adbc775d2817451845_ZmlsZXMvZ2l0bGFiLWNvbmZpZy10ZW1wbGF0ZS9naXRsYWIucmIudGVtcGxhdGU= 100644
--- a/files/gitlab-config-template/gitlab.rb.template
+++ b/files/gitlab-config-template/gitlab.rb.template
@@ -1349,8 +1349,7 @@
 # gitlab_shell['auth_file'] = "/var/opt/gitlab/.ssh/authorized_keys"
 
 ### Migration to Go feature flags
-###! Docs: https://gitlab.com/gitlab-org/gitlab-shell#migration-to-go-feature-flags
-# gitlab_shell['migration'] = { enabled: true, features: [] }
+# gitlab_shell['migration'] = { enabled: true, features: [] } # DEPRECATED: see https://gitlab.com/groups/gitlab-org/-/epics/14845.
 
 ### Git trace log file.
 ###! If set, git commands receive GIT_TRACE* environment variables
diff --git a/files/gitlab-cookbooks/package/libraries/deprecations.rb b/files/gitlab-cookbooks/package/libraries/deprecations.rb
index 8fe3700a88d75cfdecdcf433b0d1accc643cdeb1_ZmlsZXMvZ2l0bGFiLWNvb2tib29rcy9wYWNrYWdlL2xpYnJhcmllcy9kZXByZWNhdGlvbnMucmI=..6c3c5c10cccf988c426fd7adbc775d2817451845_ZmlsZXMvZ2l0bGFiLWNvb2tib29rcy9wYWNrYWdlL2xpYnJhcmllcy9kZXByZWNhdGlvbnMucmI= 100644
--- a/files/gitlab-cookbooks/package/libraries/deprecations.rb
+++ b/files/gitlab-cookbooks/package/libraries/deprecations.rb
@@ -343,6 +343,12 @@
             deprecation: '17.1',
             removal: '18.0',
             note: "`registry['default_notifications_threshold'] will be removed in 18.0. Please use `default_notifications_maxretries` instead https://gitlab.com/gitlab-org/container-registry/-/issues/1243."
+          },
+          {
+            config_keys: %w(gitlab gitlab_shell migration),
+            deprecation: '17.4',
+            removal: '18.0',
+            note: "`gitlab_shell['migration'] will be ignored from 17.3 and removed in 18.0. See https://gitlab.com/groups/gitlab-org/-/epics/14845."
           }
         ]