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
db_key_base The base key to encrypt the data for attr_encrypted columns
openid_connect_signing_key The signing key for OpenID Connect
encrypted_settings_key_base The base key to encrypt settings files with
active_record_encryption_primary_key The base key to non-deterministically-encrypt data for ActiveRecord::Encryption encrypted columns
active_record_encryption_deterministic_key The base key to deterministically-encrypt data for ActiveRecord::Encryption encrypted columns
active_record_encryption_key_derivation_salt The derivation salt to encrypt data for ActiveRecord::Encryption encrypted columns

Where the secrets are stored

Installation type Location
Linux package /etc/gitlab/gitlab-secrets.json
Cloud Native GitLab Charts Kubernetes Secrets
Self-compiled <path-to-gitlab-rails>/config/secrets.yml (Automatically generated by config/initializers/01_secret_token.rb)

Warning: Before you add a new secret to application secrets

Add support to Omnibus GitLab and the Cloud Native GitLab charts

Before you add a new secret to config/initializers/01_secret_token.rb, make sure you also update Omnibus GitLab and the Cloud Native GitLab charts, or the update will fail. Both installation methods are responsible for writing the config/secrets.yml file. If if they don’t know about a secret, Rails attempts to write to the file, and fails because it doesn’t have write access.

Examples

Populate the secrets in live environments

Additionally, in case you need the secret to have the same value on all nodes (which is usually the case), you need to make sure it’s configured for all live environments (GitLab.com, staging, pre) prior to changing this file.

Document the new secrets

Add the new secrets to this documentation file

The new secrets should be documented in doc/development/application_secrets.md.

Mention the new secrets in the next release upgrade notes

The new secrets should be mentioned in the next release notes, in the upgrade section.

For instance, for the 17.8 release, the notes would go in data/release_posts/17_8/17-8-upgrade.yml and contain something like the following: 

---
upgrades:
  - reporter: <your username>  # item author username
    description: |
      In Gitlab 17.8, three new secrets have been added to support the upcoming encryption framework:
      - `active_record_encryption_primary_key`
      - `active_record_encryption_deterministic_key`
      - `active_record_encryption_key_derivation_salt`

      **If you have a multi-node configuration, you should ensure these secrets are the same on all nodes.** Otherwise, the application will automatically generate the missing secrets.

      If you use the [GitLab helm chart](https://docs.gitlab.com/charts/) and disabled the [shared-secrets chart](https://docs.gitlab.com/charts/charts/shared-secrets/), you will need to [manually create these secrets](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-rails-secret).

Mention the new secrets in the next Cloud Native GitLab charts upgrade notes

The new secrets should be mentioned in the current major release upgrade notes.

For instance, for 8.8, you should document the new secrets in https://docs.gitlab.com/charts/releases/8_0.html.

Further iteration

We may either deprecate or remove this automatic secret generation performed by config/initializers/01_secret_token.rb in the future. See issue #222690 for more information.