Allow reading authentication tokens from a file via token_file configuration option

Summary

Add support for reading authentication tokens from a file via a new token_file configuration option, improving security and simplifying Kubernetes deployments.

Problem

Currently, Gitaly requires authentication tokens to be specified directly in the configuration file using the auth.token field:

[auth]
token = "abc123secret"

This approach has significant drawbacks:

  1. Security: Storing tokens directly in configuration files is less secure than referencing external secret files that can be managed with appropriate filesystem permissions and secret management systems.

  2. Kubernetes complexity: In Kubernetes environments, this requires rendering the configuration at startup time (e.g., using gomplate or similar templating tools) to inject secrets from mounted volumes into the config file. This adds complexity to the deployment process and introduces potential failure points during pod initialization.

  3. Operational overhead: Configuration rendering requires an init container or startup process, increasing resource usage and deployment complexity.

Proposed Solution

Add a new token_file configuration option to the [auth] section that allows Gitaly to read the authentication token from a file at runtime:

[auth]
token_file = "/etc/gitaly-secrets/token"

Implementation Details

  • Only one of token or token_file can be set; Gitaly should fail to start if both are configured
  • If neither is set, authentication remains disabled (existing behavior)
  • Whitespace should be automatically trimmed from the file contents
  • The token file is read at startup time
  • Clear error messages should be provided if the file cannot be read

Benefits

  1. Improved security: Tokens stored in separate files can have restrictive permissions (0400/0600) and be managed by dedicated secret management systems
  2. Simplified Kubernetes deployments: Eliminates the need for configuration rendering at startup - secrets can be mounted directly from Kubernetes Secrets without templating
  3. Reduced complexity: Removes the need for init containers or gomplate processing
  4. Better alignment with cloud-native practices: Follows the common pattern used by many other tools (e.g., Docker, Kubernetes components) for secret management

Related Work

Many production systems follow this pattern:

  • Docker uses --password-stdin and credential files
  • Kubernetes components read tokens from files mounted via Secrets
  • PostgreSQL supports password files via PGPASSFILE
  • AWS CLI uses credential files

Documentation Updates

The following documentation should be updated:

  • config.toml.example - Add examples for both token and token_file
  • doc/configuration/README.md - Document both options and security best practices
  • Kubernetes deployment guides - Simplify configuration by removing rendering step

Related to gitlab-org#20677

cc @mjwood @WarheadsSE