config

package
v1.102.0 Latest Latest
Warning

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

 Go to latest Published: Jun 5, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var KeySchema = []KeyDef{

	{
		Name: "git_protocol", Scope: ScopeGlobal, Type: TypeString,
		Default: "ssh", UserSettable: true, Fallback: true,
		Description: "What protocol to use when performing Git operations. Supported values: ssh, https.",
	},
	{
		Name: "branch_prefix", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "Prefix used by 'glab stack' when naming generated branches. Defaults to the\n$USER environment variable, falling back to 'glab-stack' when unset.",
	},
	{
		Name: "remote_alias", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Aliases:      []string{"git_remote_url_var", "git_remote_alias", "remote_nickname", "git_remote_nickname"},
		EnvVars:      []string{"GIT_REMOTE_URL_VAR", "GIT_REMOTE_ALIAS", "REMOTE_ALIAS", "REMOTE_NICKNAME", "GIT_REMOTE_NICKNAME"},
		Description:  "Name of the 'git remote' that points at the GitLab repository. Used to\nresolve which remote to operate against when multiple are configured.",
	},
	{
		Name: "editor", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Aliases:      []string{"visual", "glab_editor"},
		EnvVars:      []string{"GLAB_EDITOR", "VISUAL", "EDITOR"},
		Description:  "What editor glab should run when creating issues, merge requests, etc. This global config cannot be overridden by hostname.",
	},
	{
		Name: "browser", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "What browser glab should run when opening links. This global config cannot be overridden by hostname.",
	},
	{
		Name: "glamour_style", Scope: ScopeGlobal, Type: TypeString,
		Default: "dark", UserSettable: true, Fallback: true,
		Description: "Set your desired Markdown renderer style. Available options are [dark, light, notty]. To set a custom style, refer to https://github.com/charmbracelet/glamour#styles",
	},
	{
		Name: "check_update", Scope: ScopeGlobal, Type: TypeBool,
		Default: "true", UserSettable: true,
		Description: "Allow glab to automatically check for updates and notify you when there are new updates.",
	},
	{
		Name: "last_update_check_timestamp", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "Last update check timestamp, used for checking when the last update check was performed.",
	},
	{
		Name: "show_whats_new", Scope: ScopeGlobal, Type: TypeBool,
		Default: "true", UserSettable: true,
		EnvVars:     []string{"GLAB_SHOW_WHATS_NEW"},
		Description: "Show a one-time post-upgrade banner pointing at 'glab whatsnew' when a new version is detected.",
	},
	{
		Name: "last_seen_version", Scope: ScopeGlobal, Type: TypeString,

		Default: "v1.100.0", UserSettable: true, Fallback: true,
		Description: "Last glab version a post-upgrade banner was shown for (automatically set).",
	},
	{
		Name: "last_whatsnew_version", Scope: ScopeGlobal, Type: TypeString,

		Default: "v1.100.0", UserSettable: true, Fallback: true,
		Description: "Last glab version 'glab whatsnew' rendered notes for (automatically set).",
	},
	{
		Name: "notify_skill_updates", Scope: ScopeGlobal, Type: TypeBool,
		Default: "true", UserSettable: true,
		EnvVars:     []string{"GLAB_NOTIFY_SKILL_UPDATES"},
		Description: "Show a notice when an installed agent skill (bundled or remote) has updates available.",
	},
	{
		Name: "display_hyperlinks", Scope: ScopeGlobal, Type: TypeBool,
		Default: "true", UserSettable: true,
		Description: "Whether or not to display hyperlinks in terminal output. Defaults to true (enabled for TTYs). Set to false to disable. Force hyperlinks in non-TTY environments by setting FORCE_HYPERLINKS=1.",
	},
	{
		Name: "host", Scope: ScopeGlobal, Type: TypeString,
		Default: "gitlab.com", UserSettable: true,
		Aliases:     []string{"gitlab_host", "gitlab_uri", "gl_host"},
		EnvVars:     []string{"GITLAB_HOST", "GITLAB_URI", "GL_HOST"},
		Description: "Default GitLab hostname to use.",
	},
	{
		Name: "no_prompt", Scope: ScopeGlobal, Type: TypeBool,
		Default: "false", UserSettable: true,
		Aliases:     []string{"prompt_disabled"},
		EnvVars:     []string{"NO_PROMPT", "PROMPT_DISABLED"},
		Description: "Set to true (1) to disable prompts, or false (0) to enable them.",
	},
	{
		Name: "telemetry", Scope: ScopeGlobal, Type: TypeBool,
		Default: "true", UserSettable: true,
		EnvVars:     []string{"GLAB_SEND_TELEMETRY"},
		Description: "Set to false (0) to disable sending usage data to your GitLab instance or true (1) to enable.\nSee https://docs.gitlab.com/administration/settings/usage_statistics/\nfor more information",
	},

	{
		Name: "duo_cli_auto_run", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "Automatically run GitLab Duo CLI without prompting (true/false). Set to true to skip the confirmation prompt.",
	},
	{
		Name: "duo_cli_auto_download", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "Automatically download Duo CLI binary without prompting (true/false).",
	},
	{
		Name: "duo_cli_binary_path", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		EnvVars:      []string{"GLAB_DUO_CLI_BINARY_PATH"},
		Description:  "Path to the installed Duo CLI binary (automatically set). Default: ~/.config/glab-cli/bin/duo",
	},
	{
		Name: "duo_cli_binary_version", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "Version of the installed Duo CLI binary (automatically set).",
	},
	{
		Name: "duo_cli_binary_checksum", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "SHA256 checksum of the installed Duo CLI binary (automatically set).",
	},
	{
		Name: "duo_cli_last_update_check", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "Last time an update check was performed (automatically set).",
	},

	{
		Name: "orbit_local_auto_run", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "Automatically run Orbit local CLI without prompting (true/false). Set to true to skip the confirmation prompt.",
	},
	{
		Name: "orbit_local_auto_download", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "Automatically download Orbit local CLI binary without prompting (true/false).",
	},
	{
		Name: "orbit_local_binary_path", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		EnvVars:      []string{"GLAB_ORBIT_LOCAL_BINARY_PATH"},
		Description:  "Path to the installed Orbit local CLI binary (automatically set). Default: ~/.config/glab-cli/bin/orbit",
	},
	{
		Name: "orbit_local_binary_version", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "Version of the installed Orbit local CLI binary (automatically set).",
	},
	{
		Name: "orbit_local_binary_checksum", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "SHA256 checksum of the installed Orbit local CLI binary (automatically set).",
	},
	{
		Name: "orbit_local_last_update_check", Scope: ScopeGlobal, Type: TypeString,
		UserSettable: true,
		Description:  "Last time an Orbit local CLI update check was performed (automatically set).",
	},

	{
		Name: "api_protocol", Scope: ScopePerHost, Type: TypeString,
		Default: "https", UserSettable: true, Fallback: true,
		Description: "What protocol to use to access the API endpoint. Supported values: http, https.",
	},
	{
		Name: "api_host", Scope: ScopePerHost, Type: TypeString,
		Default: "gitlab.com", UserSettable: true,
		Aliases:     []string{"gitlab_api_host"},
		EnvVars:     []string{"GITLAB_API_HOST"},
		Description: "Configure host for API endpoint. Defaults to the host itself.",
	},
	{
		Name: "subfolder", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true,
		Aliases:      []string{"gitlab_subfolder"},
		EnvVars:      []string{"GITLAB_SUBFOLDER"},
		Description:  "Subfolder where GitLab is installed (e.g., 'gitlab' for https://example.com/gitlab/)\nUse this when GitLab is hosted at a subfolder rather than domain root.\nSupports nested paths (e.g., 'apps/gitlab' for https://example.com/apps/gitlab/)\nSlashes are automatically trimmed, so 'gitlab', '/gitlab', and 'gitlab/' are equivalent.\nOnly applies to HTTP/HTTPS operations (API and git clone).",
	},
	{
		Name: "ssh_host", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true,
		Aliases:      []string{"gitlab_ssh_host"},
		EnvVars:      []string{"GITLAB_SSH_HOST"},
		Description:  "Alternate hostname for SSH git operations (e.g., 'ssh.example.com' or 'git.example.com')\nUse this when SSH uses a different hostname than HTTP/API operations.\nOnly affects SSH cloning and git operations.",
	},
	{
		Name: "token", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true, Keyring: true,
		Aliases:     []string{"gitlab_token", "oauth_token"},
		EnvVars:     []string{"GITLAB_TOKEN", "GITLAB_ACCESS_TOKEN", "OAUTH_TOKEN"},
		Description: "Your GitLab access token. To get one, read https://docs.gitlab.com/user/profile/personal_access_tokens/",
	},
	{
		Name: "job_token", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true, Keyring: true,
		Description: "CI job token used for Job-Token authentication. Typically populated\nautomatically from CI_JOB_TOKEN when CI auto-login is enabled.",
	},
	{
		Name: "user", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true,
		EnvVars:      []string{"GLAB_USER"},
		Description:  "Username associated with the configured token. Set automatically on login.",
	},
	{
		Name: "client_id", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true,
		EnvVars:      []string{"GITLAB_CLIENT_ID"},
		Description:  "OAuth application client ID. Required when authenticating with OAuth\nagainst a self-managed GitLab instance.",
	},
	{
		Name: "use_keyring", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true,
		Description:  "Store the host's credentials in the operating system's keyring (true/false).\nSet automatically by 'glab auth login'. Empty is treated as false.",
	},
	{
		Name: "proxy", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true,
		Description:  "Custom proxy for this host. Overrides environment proxy settings when set.",
	},
	{
		Name: "ca_cert", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true,
		Description:  "Path to a CA certificate (PEM) used to verify the GitLab server's\nTLS certificate. Useful for self-signed or private CAs.",
	},
	{
		Name: "client_cert", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true,
		Description:  "Path to a client certificate (PEM) used for mutual TLS authentication.",
	},
	{
		Name: "client_key", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true,
		Description:  "Path to the private key (PEM) that matches client_cert.",
	},
	{
		Name: "skip_tls_verify", Scope: ScopePerHost, Type: TypeString,
		UserSettable: true,
		Description:  "Skip TLS certificate verification when talking to this host (true/false).\nEmpty is treated as false. Use only for development; do not enable in production.",
	},
	{
		Name: "container_registry_domains", Scope: ScopePerHost, Type: TypeString,
		Default: "gitlab.com,gitlab.com:443,registry.gitlab.com", UserSettable: true,
		Description: "The domains of associated container registries. These are used to configure the\nDocker credential helper.",
	},
	{
		Name: "custom_headers", Scope: ScopePerHost, Type: TypeList,
		UserSettable: true,
		Description:  "Custom HTTP headers to add to all HTTP requests made by glab. Supports both direct values and environment variable loading.\n- name: Proxy-Authorization\n  value: Bearer token123\n- name: Cf-Access-Client-Secret\n  valueFromEnv: MY_SECRET_VALUE",
	},

	{
		Name: "is_oauth2", Scope: ScopePerHost, Type: TypeString,
		UserSettable: false,
		EnvVars:      []string{"GLAB_IS_OAUTH2"},
		Description:  "CLI-managed flag indicating the host was authenticated via OAuth.",
	},
	{
		Name: "oauth2_refresh_token", Scope: ScopePerHost, Type: TypeString,
		UserSettable: false, Keyring: true,
		Description: "CLI-managed OAuth refresh token. Written by 'glab auth login'.",
	},
	{
		Name: "oauth2_expiry_date", Scope: ScopePerHost, Type: TypeString,
		UserSettable: false,
		Description:  "CLI-managed OAuth token expiry timestamp.",
	},
	{
		Name: "refresh_token", Scope: ScopePerHost, Type: TypeString,
		UserSettable: false,
		Description:  "CLI-managed refresh token; superseded by oauth2_refresh_token.",
	},
}

KeySchema is the declared list of every config key glab understands. Order is preserved when building the blank config.

Functions

func BackupConfigFile 

func BackupConfigFile(filename string) error

BackupConfigFile creates a backup of the provided config file

func CheckFileExists 

func CheckFileExists(filename string) bool

CheckFileExists: checks if a file exists and is not a directory.

func CheckPathExists 

func CheckPathExists(path string) bool

CheckPathExists checks if a folder exists and is a directory

func ConfigDir 

func ConfigDir() string

ConfigDir returns the config directory for writing configuration. It respects GLAB_CONFIG_DIR as the highest priority override. For backward compatibility, if a legacy config exists at ~/.config/glab-cli/, that location continues to be used. Otherwise, uses XDG_CONFIG_HOME.

func ConfigFile 

func ConfigFile() string

ConfigFile returns the config file path. It respects GLAB_CONFIG_DIR as the highest priority override, otherwise returns the XDG-compliant user config file path. This function only determines the path without creating directories.

func ConfigKeyEquivalence 

func ConfigKeyEquivalence(key string) string

func EnvKeyEquivalence 

func EnvKeyEquivalence(key string) []string

func GetFromEnv 

func GetFromEnv(key string) string

GetFromEnv is just a wrapper for os.GetEnv but checks for matching names used in previous glab versions and retrieves the value of the environment if any of the matching names have been set. It returns the value, which will be empty if the variable is not present.

func GetFromEnvWithSource 

func GetFromEnvWithSource(key string) (string, string)

GetFromEnvWithSource works like GetFromEnv but also returns the name of the environment variable that was set as the source.

func GitDir added in v1.59.0 

func GitDir(preferRelative bool) []string

for later use we might prefer relative paths GitDir will find a directory or just return ".git"

func HasSecurePerms added in v1.44.0 

func HasSecurePerms(m fs.FileMode) bool

func IsKnownKey added in v1.102.0 

func IsKnownKey(key string) bool

func KnownKeys added in v1.102.0 

func KnownKeys() map[string]struct{}

func LocalConfigDir 

func LocalConfigDir() []string

LocalConfigDir returns the local config path in map which must be joined for complete path

func LocalConfigFile 

func LocalConfigFile() string

LocalConfigFile returns the config file name with full path

func NewBlankRoot 

func NewBlankRoot() *yaml.Node

func ParseConfigFile added in v1.29.0 

func ParseConfigFile(filename string) ([]byte, *yaml.Node, error)

func ResolveCustomHeaders added in v1.73.0 

func ResolveCustomHeaders(cfg Config, hostname string) (map[string]string, error)

ResolveCustomHeaders is a helper function that works with the Config interface

func ResolveHostProxy added in v1.86.0 

func ResolveHostProxy(cfg Config, hostname string) (*url.URL, error)

ResolveHostProxy exposes per-host proxy resolution for consumers.

func SearchConfigFile added in v1.75.0 

func SearchConfigFile() (string, error)

SearchConfigFile searches for an existing config file across all config paths. It respects GLAB_CONFIG_DIR as the highest priority override. Search order: 1. $GLAB_CONFIG_DIR/config.yml (if GLAB_CONFIG_DIR is set) 2. ~/.config/glab-cli/config.yml (legacy location, for backward compatibility) 3. $XDG_CONFIG_HOME/glab-cli/config.yml (platform-specific XDG location) 4. $XDG_CONFIG_DIRS/glab-cli/config.yml (system-wide configs)

Returns the path to the first config file found, or an error if none exist.

func TrimmedFileContents added in v1.54.0 

func TrimmedFileContents(filePath string) (string, error)

func WriteFile 

func WriteFile(filename string, data []byte, perm os.FileMode) error

WriteFile to the path If the path is smylink it will write to the symlink

Types

type AliasConfig 

type AliasConfig struct {
	ConfigMap
	Parent Config
	// contains filtered or unexported fields
}

func (*AliasConfig) All 

func (a *AliasConfig) All() map[string]string

func (*AliasConfig) Delete 

func (a *AliasConfig) Delete(alias string) error

func (*AliasConfig) Get 

func (a *AliasConfig) Get(alias string) (string, bool)

func (*AliasConfig) Set 

func (a *AliasConfig) Set(alias, expansion string) error

func (*AliasConfig) Write 

func (a *AliasConfig) Write() error

type Config 

type Config interface {
	Get(string, string) (string, error)
	GetWithSource(string, string, bool) (string, string, error)
	Set(string, string, string) error
	Hosts() ([]string, error)
	Aliases() (*AliasConfig, error)
	Local() (*LocalConfig, error)
	// Write writes to the config.yml file
	Write() error
	// WriteAll saves all the available configuration file types
	WriteAll() error
}

A Config reads and writes persistent configuration for glab.

func Init 

func Init() (Config, error)

Init initialises and returns the cached configuration

func NewBlankConfig 

func NewBlankConfig() Config

NewBlankConfig initializes an in-memory config pre-populated with comments and default values. It has no directory behind it, so Write()/WriteAll() are no-ops.

func NewBlankConfigInDir added in v1.102.0 

func NewBlankConfigInDir(dir string) Config

NewBlankConfigInDir initializes a blank config that persists to dir.

func NewConfig 

func NewConfig(root *yaml.Node) Config

func NewFromString 

func NewFromString(str string) Config

NewFromString initializes an in-memory Config from a yaml string. It has no directory behind it, so Write()/WriteAll() are no-ops.

func NewFromStringInDir added in v1.102.0 

func NewFromStringInDir(str, dir string) Config

NewFromStringInDir initializes a Config from a yaml string that persists to dir. Intended for tests that need to inspect what would be written to disk.

func ParseConfig 

func ParseConfig(filename string) (Config, error)

ParseConfig reads the main config from filename and the aliases file from the same directory. It does not read a separate local config file; callers that need local (per-repository) overrides merged in pass the path explicitly via parseConfig.

func ParseDefaultConfig 

func ParseDefaultConfig() (Config, error)

type ConfigEntry 

type ConfigEntry struct {
	KeyNode   *yaml.Node
	ValueNode *yaml.Node
	Index     int
}

type ConfigMap 

type ConfigMap struct {
	Root *yaml.Node
}

ConfigMap type implements a low-level get/set config that is backed by an in-memory tree of YAML nodes. It allows us to interact with a YAML-based config programmatically, preserving any comments that were present when the YAML was parsed.

func (*ConfigMap) Empty 

func (cm *ConfigMap) Empty() bool

func (*ConfigMap) FindEntry 

func (cm *ConfigMap) FindEntry(key string) (*ConfigEntry, error)

func (*ConfigMap) GetStringValue 

func (cm *ConfigMap) GetStringValue(key string) (string, error)

func (*ConfigMap) RemoveEntry 

func (cm *ConfigMap) RemoveEntry(key string)

func (*ConfigMap) SetStringValue 

func (cm *ConfigMap) SetStringValue(key, value string) error

type CustomHeader added in v1.73.0 

type CustomHeader struct {
	Name         string `yaml:"name"`
	Value        string `yaml:"value,omitempty"`
	ValueFromEnv string `yaml:"valueFromEnv,omitempty"`
}

CustomHeader represents a single custom HTTP header configuration

func (*CustomHeader) ResolvedValue added in v1.73.0 

func (h *CustomHeader) ResolvedValue() (string, error)

ResolvedValue returns the actual header value, resolving environment variables if needed

type HostConfig 

type HostConfig struct {
	ConfigMap
	Host string
}

HostConfig represents the configuration for a single host.

func (*HostConfig) GetCustomHeaders added in v1.73.0 

func (hc *HostConfig) GetCustomHeaders() ([]CustomHeader, error)

GetCustomHeaders returns the custom headers for a specific host

type KeyDef added in v1.102.0 

type KeyDef struct {
	Name  string
	Scope Scope
	Type  ValueType
	// Default is the YAML scalar seed value. For TypeList it's ignored
	// and an empty sequence is emitted instead.
	Default     string
	Description string
	// EnvVars overrides the default env-var (uppercase Name). CI-autologin
	// overrides are layered on top by EnvKeyEquivalence.
	EnvVars []string
	Aliases []string
	// UserSettable false keeps the key off `config set` and out of the
	// blank config, but Get and env-var lookups still resolve it.
	UserSettable bool
	Keyring      bool
	// Fallback makes Default apply to runtime Get calls when the key is
	// missing from the config, not just to the blank-config seed.
	Fallback bool
}

KeyDef is the single source of truth for a config key. It drives NewBlankConfig, KnownKeys, defaultFor, ConfigKeyEquivalence, EnvKeyEquivalence, and keyring eligibility.

type LocalConfig 

type LocalConfig struct {
	ConfigMap
	Parent Config
	// contains filtered or unexported fields
}

func (*LocalConfig) All 

func (a *LocalConfig) All() map[string]string

func (*LocalConfig) Delete 

func (a *LocalConfig) Delete(key string) error

func (*LocalConfig) Get 

func (a *LocalConfig) Get(key string) (string, bool)

func (*LocalConfig) Set 

func (a *LocalConfig) Set(key, value string) error

func (*LocalConfig) Write 

func (a *LocalConfig) Write() error

type NotFoundError 

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

NotFoundError is returned when a config entry is not found.

type Scope added in v1.102.0 

type Scope int
const (
	ScopeGlobal Scope = iota
	ScopePerHost
)

type ValueType added in v1.102.0 

type ValueType int
const (
	TypeString ValueType = iota
	TypeBool
	TypeList
)

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.