Help us shape the future of Go! Take the 2026 Go Developer Survey

config

package
v4.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package config loads and validates the runtime configuration.

Environment variables (GITLAB_MCP_*) are the source of truth, because an MCP client passes only command, args and env to a stdio server. Most settings also have a flag bound to the same name; a flag given on the command line wins over the environment, and the environment over the default. Build validates once and reports every problem together, so a misconfigured server fails before it announces itself.

Every variable is read through Lookup, so spaces alone are unset and the spaces around a value are dropped, whichever package reads it.

Vars lists every variable. Define binds from it, and the staleness gate holds docs/configuration.md (and, for the development override, docs/development.md) against it, so a setting cannot be added without being documented.

Index

Constants

View Source
const (
	MinHTTPTimeout = time.Second
	MaxHTTPTimeout = 10 * time.Minute
)

HTTP timeout bounds. Below a second nothing completes; above ten minutes a hung call holds the client longer than anyone waits.

View Source
const (
	EnvProfile           = EnvPrefix + "PROFILE"
	EnvClientID          = EnvPrefix + "CLIENT_ID"
	EnvReadOnly          = EnvPrefix + "READ_ONLY"
	EnvEnableShip        = EnvPrefix + "ENABLE_SHIP"
	EnvEnableDestructive = EnvPrefix + "ENABLE_DESTRUCTIVE"
	// EnvRequirePrompt was removed with the server's question (§4.12);
	// it is read only to refuse it set.
	EnvRequirePrompt             = EnvPrefix + "REQUIRE_PROMPT"
	EnvToolsets                  = EnvPrefix + "TOOLSETS"
	EnvWriteNamespaces           = EnvPrefix + "WRITE_NAMESPACES"
	EnvUploadDirs                = EnvPrefix + "UPLOAD_DIRS"
	EnvLogLevel                  = EnvPrefix + "LOG_LEVEL"
	EnvLogFormat                 = EnvPrefix + "LOG_FORMAT"
	EnvHTTPTimeout               = EnvPrefix + "HTTP_TIMEOUT"
	EnvConfigDir                 = EnvPrefix + "CONFIG_DIR"
	EnvConfigDirAllowOutsideHome = EnvPrefix + "CONFIG_DIR_ALLOW_OUTSIDE_HOME"
	// EnvRefreshToken is read by internal/credentials, never by Define,
	// and has no flag: a secret on a command line is visible to every
	// process on the machine.
	EnvRefreshToken = EnvPrefix + "REFRESH_TOKEN"
	// EnvTestInstance points the server at a loopback stand-in for
	// gitlab.com: the in-memory instance the tests, the evals and the
	// smoke gate run. It has no flag and is refused for any other host,
	// so it cannot send a token to a real one.
	EnvTestInstance = EnvPrefix + "TEST_INSTANCE"
)

Variable names.

View Source
const DefaultHTTPTimeout = 60 * time.Second

DefaultHTTPTimeout bounds how long a call to GitLab may go without progress: while its request body is sent, waiting for the answer to start once it is, and between reads of the answer.

View Source
const EnvPrefix = "GITLAB_MCP_"

EnvPrefix is prepended to every environment variable name. Not GITLAB_: CI jobs already set GITLAB_CI, GITLAB_USER_LOGIN and more (§18 row 30).

View Source
const ToolsetAll = "all"

ToolsetAll names every toolset at once.

Variables

View Source
var ErrInvalid = errors.New("config: invalid")

ErrInvalid wraps every validation failure.

View Source
var Toolsets = []string{"activity", "deployments", "planning", "releases", "snippets", "wiki"}

Toolsets are the optional toolsets, sorted, which are off unless named (§4.3).

View Source
var Vars = []Var{
	{Name: EnvProfile, Flag: "profile",
		Doc: "named sign-in profile; unset means \"default\""},
	{Name: EnvClientID, Flag: "client-id",
		Doc: "the OAuth application id (overrides the stored profile's)"},
	{Name: EnvReadOnly, Flag: "read-only", Default: "false", Switch: true,
		Doc: "register only the read tools and request read_api"},
	{Name: EnvEnableShip, Flag: "enable-ship", Default: "false", Switch: true,
		Doc: "register merging, approving, running CI and creating releases"},
	{Name: EnvEnableDestructive, Flag: "enable-destructive", Default: "false", Switch: true,
		Doc: "register deletions, each of which also needs confirm: true"},
	{Name: EnvToolsets, Flag: "toolsets",
		Doc: "comma-separated optional toolsets: " + strings.Join(Toolsets, ", ") + ", or all"},
	{Name: EnvWriteNamespaces, Flag: "write-namespaces",
		Doc: "comma-separated groups or projects that writes are confined to; unset means anywhere"},
	{Name: EnvUploadDirs, Flag: "upload-dirs",
		Doc: "absolute directories upload_file may read images from, separated as PATH is; unset means none"},
	{Name: EnvLogLevel, Flag: "log-level", Default: string(LogInfo),
		Doc: "log level: debug, info, warn, error"},
	{Name: EnvLogFormat, Flag: "log-format", Default: string(LogText),
		Doc: "log format: text, json"},
	{Name: EnvHTTPTimeout, Flag: "http-timeout", Default: DefaultHTTPTimeout.String(),
		Doc: "how long a call to GitLab may go without progress: sending, waiting for the answer, reading it; between 1s and 10m"},
	{Name: EnvConfigDir, Flag: "config-dir",
		Doc: "directory for profiles; must be inside your home directory"},
	{Name: EnvConfigDirAllowOutsideHome, Default: "false", Switch: true,
		Doc: "accept a config directory outside your home directory"},
	{Name: EnvRefreshToken, Outside: true, Secret: true,
		Doc: "a refresh token to use instead of the stored one (CI, automation)"},
	{Name: EnvTestInstance, Dev: true,
		Doc: "a loopback base URL that stands in for gitlab.com, for tests only"},
}

Vars is every variable this server reads, in documentation order.

Functions

func DevVars

func DevVars() []string

DevVars is every development override, sorted.

func EnvVars

func EnvVars() []string

EnvVars is every variable a person running the server may set, sorted: Vars less the development overrides.

func Lookup added in v4.1.3

func Lookup(env func(string) string, name string) string

Lookup is the value env gives the variable name, without the spaces around it. Spaces alone are "", unset as an empty variable is, so a form field cleared to a space means the default rather than a value the server refuses. Define reads every variable through it, and so does each reader outside Define.

func NewLogger

func NewLogger(c Config, w io.Writer) *slog.Logger

NewLogger builds the process logger. w must be stderr on the server path: stdout carries only JSON-RPC frames.

func RemovedVars

func RemovedVars() []string

RemovedVars are variables a release removed that the server still reads, only to refuse one turned on, sorted.

Types

type Config

type Config struct {
	// Instance is gitlab.com, or the loopback stand-in of
	// GITLAB_MCP_TEST_INSTANCE. Zero means gitlab.com; use Target.
	Instance instance.Instance
	// TestInstance says GITLAB_MCP_TEST_INSTANCE is set.
	TestInstance bool
	// Profile is the profile named, or empty for "default".
	Profile string
	// ClientID overrides the profile's stored OAuth application id.
	ClientID string
	// ReadOnly registers the Read kind only and requests read_api.
	ReadOnly bool
	// EnableShip registers the Ship kind. It changes no scope (§9.4).
	EnableShip bool
	// EnableDestructive registers the Destructive kind. It changes no
	// scope either.
	EnableDestructive bool
	// Toolsets are the optional toolsets turned on, sorted, with "all"
	// expanded.
	Toolsets []string
	// WriteNamespaces confine every write, of any kind (§4.7). Empty
	// means no confinement.
	WriteNamespaces []string
	// UploadDirs are the only directories upload_file may read an image
	// from (§7.10). Empty means none: the tool refuses every path.
	UploadDirs  []string
	LogLevel    LogLevel
	LogFormat   LogFormat
	HTTPTimeout time.Duration
	// ConfigDir is the resolved base directory for profiles.
	ConfigDir userconfig.Dir
}

Config is the validated runtime configuration.

func Load

func Load(args []string, env func(string) string) (Config, error)

Load is Define, Parse and Build for a caller with no flags of its own.

func (Config) Mode

func (c Config) Mode() scopes.Mode

Mode is the scope mode this configuration is in.

func (Config) Scopes

func (c Config) Scopes() []string

Scopes is what login requests under this configuration.

func (Config) Target

func (c Config) Target() instance.Instance

Target is the instance this configuration talks to: gitlab.com unless the test override names another.

func (Config) ToolsetEnabled

func (c Config) ToolsetEnabled(name string) bool

ToolsetEnabled reports whether an optional toolset is on.

type LogFormat

type LogFormat string

LogFormat is a typed enum constrained at load time.

const (
	LogText LogFormat = "text"
	LogJSON LogFormat = "json"
)

Allowed LogFormat values.

type LogLevel

type LogLevel string

LogLevel is a typed enum constrained at load time.

const (
	LogDebug LogLevel = "debug"
	LogInfo  LogLevel = "info"
	LogWarn  LogLevel = "warn"
	LogError LogLevel = "error"
)

Allowed LogLevel values.

func (LogLevel) Slog

func (l LogLevel) Slog() slog.Level

Slog returns the slog.Level for this level.

type Settings

type Settings struct {
	// contains filtered or unexported fields
}

Settings holds the raw values before validation, keyed by variable, the removed ones included.

func Define

func Define(fs *flag.FlagSet, env func(string) string) *Settings

Define registers one flag per flagged variable on fs, each defaulting to its environment variable read through Lookup, and reads the environment-only variables; a variable read outside Define is left to its reader.

func (*Settings) Build

func (s *Settings) Build() (Config, error)

Build validates the settings and returns a Config, or every problem at once.

type Var

type Var struct {
	// Name is the environment variable.
	Name string
	// Flag is the command-line flag bound to it, without dashes; empty
	// for a variable read from the environment only.
	Flag string
	// Default is the value used when neither is given.
	Default string
	// Doc says what it does.
	Doc string
	// Switch marks a boolean: a bare --flag means true.
	Switch bool
	// Dev marks a development override: documented in
	// docs/development.md rather than docs/configuration.md, and never
	// offered to the people running the server.
	Dev bool
	// Outside marks a variable read outside Define, by the package that
	// uses it and through Lookup. Define skips it, and it has no flag.
	Outside bool
	// Secret marks a credential. A bundle field that sets one is
	// sensitive, so a host keeps the value out of sight.
	Secret bool
}

Var is one configuration variable.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL