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

config

package
v2.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 10, 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.

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             = 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 Build,
	// 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: EnvRequirePrompt, Flag: "require-prompt", Default: "false", Switch: true,
		Doc: "refuse the writes that ask the person when the client cannot ask them"},
	{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,
		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 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.

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
	// RequirePrompt refuses the writes that ask the person when the
	// client cannot ask (§4.12).
	RequirePrompt bool
	// Toolsets are the optional toolsets turned on, sorted, with "all"
	// expanded.
	Toolsets []string
	// WriteNamespaces confine Write, Ship and Destructive (§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.

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 env, and reads the environment-only variables.

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
}

Var is one configuration variable.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.