Show explicit warning when we add a new secret

This commit adds a warning when dev adds a new secret

config/initializers/01_secret_token.rb

-# WARNING: If you add a new secret to this file, make sure you also
-# update Omnibus GitLab or updates will fail. Omnibus is responsible for
-# writing the `secrets.yml` file.  If Omnibus doesn't know about a
-# secret, Rails will attempt to write to the file, but this will fail
-# because Rails doesn't have write access.
-#
-# As an example:
-# * https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/27581
-# * https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/3267
-#
+# WARNING: Before you make a change to secrets.yml, read the development guide for GitLab secrets
+# doc/development/application_secrets.md.
 #
 # This file needs to be loaded BEFORE any initializers that attempt to
 # prepend modules that require access to secrets (e.g. EE's 0_as_concern.rb).

doc/development/application_secrets.md

+# Application secrets
+
+This page is a development guide for application secrets.
+
+## Secret entries
+
+|Entry                             |Description                                                        |
+|---                               |---                                                                |
+|`secret_key_base`                 | The base key to be used for generating a various secrets          |
+| `otp_key_base`                   | The base key for One Time Passwords, described in [User management](../raketasks/user_management.md#rotate-two-factor-authentication-encryption-key)              |
+|`db_key_base`                     | The base key to encrypt the data for `attr_encrypted` columns     |
+|`openid_connect_signing_key`      | The singing key for OpenID Connect                                |
+
+## Where the secrets are stored
+
+|Installation type                  |Location                                                          |
+|---                                |---                                                               |
+|Omnibus                            |[`/etc/gitlab/gitlab-secrets.json`](https://docs.gitlab.com/omnibus/settings/backups.html#backup-and-restore-omnibus-gitlab-configuration)                                 |
+|Cloud Native GitLab Charts         |[Kubernets Secrets](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/f65c3d37fc8cf09a7987544680413552fb666aac/doc/installation/secrets.md#gitlab-rails-secret)|
+|Source                             |`<path-to-gitlab-rails>/config/secrets.yml` (Automatically generated by [01_secret_token.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/01_secret_token.rb))                       |
+
+## Warning: Before you add a new secret to application secrets
+
+Before you add a new secret to [`config/initializers/01_secret_token.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/01_secret_token.rb),
+make sure you also update Omnibus GitLab or updates will fail. Omnibus is responsible for writing the `secrets.yml` file.
+If Omnibus doesn't know about a secret, Rails will attempt to write to the file, but this will fail because Rails doesn't have write access.
+The same rules apply to Cloud Native GitLab charts, you must update the charts at first.
+In case you need the secret to have same value on each node (which is usually the case) you need to make sure it's configured for all
+GitLab.com environments prior to changing this file.
+
+**Examples**
+
+- [Change for source installation](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/27581)
+- [Change for omnibus installation](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/3267)
+- [Change for omnibus installation](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4158)
+- [Change for Cloud Native installation](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/1318)
+
+## Further iteration
+
+We might deprecate/remove this automatic secret generation '01_secret_token.rb' in the future.
+Please see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/222690) for more information.

spec/initializers/secret_token_spec.rb

@@ -19,6 +19,30 @@ describe 'create_tokens' do
     allow(self).to receive(:exit)
   end
 
+  describe 'ensure acknowledged secrets in any installations' do
+    let(:acknowledged_secrets) do
+      %w[secret_key_base otp_key_base db_key_base openid_connect_signing_key]
+    end
+
+    it 'does not allow to add a new secret without a proper handling' do
+      create_tokens
+
+      secrets_hash = YAML.load_file(Rails.root.join('config/secrets.yml'))
+
+      secrets_hash.each do |environment, secrets|
+        new_secrets = secrets.keys - acknowledged_secrets
+
+        expect(new_secrets).to be_empty,
+         <<~EOS
+           CAUTION:
+           It looks like you have just added new secret(s) #{new_secrets.inspect} to the secrets.yml.
+           Please read the development guide for GitLab secrets at doc/development/application_secrets.md before you proceed this change.
+           If you're absolutely sure that the change is safe, please add the new secrets to the 'acknowledged_secrets' in order to silence this warning.
+         EOS
+      end
+    end
+  end
+
   context 'setting secret keys' do
     context 'when none of the secrets exist' do
       before do