Documentation
¶
Overview ¶
Package config manages the CLI's user-level configuration file.
Config file location follows XDG Base Directory Specification:
- $XDG_CONFIG_HOME/circleci/config.yml (when XDG_CONFIG_HOME is set)
- ~/.config/circleci/config.yml (default)
Index ¶
- Constants
- func ActiveTelemetryOverrides() []string
- func ExtensionsDir() (string, error)
- func LockPath(path string) string
- func Path() (string, error)
- func SaveState(ctx context.Context, path string, mutate func(*State) error) (err error)
- func SetHost(ctx context.Context, host string) error
- func SetTelemetry(ctx context.Context, enabled bool, path string) error
- func SetTheme(ctx context.Context, theme string) error
- func SetUpdateCheck(ctx context.Context, enabled bool, path string) error
- func StateDir() (string, error)
- func StatePath() (string, error)
- func UnsetUpdateCheck(ctx context.Context, path string) error
- type Config
- func (c *Config) DeviceID() uuid.UUID
- func (c *Config) EffectiveExtensionHost() string
- func (c *Config) EffectiveHost() string
- func (c *Config) EffectiveTheme() string
- func (c *Config) EffectiveToken() string
- func (c *Config) IsTelemetry() bool
- func (c *Config) IsUpdateCheck() bool
- func (c *Config) UserID() uuid.UUID
- type Release
- type SaveResult
- func DeleteToken(ctx context.Context, secureStorage bool) (SaveResult, error)
- func SetLogin(ctx context.Context, path, host, token string, userID uuid.UUID, ...) (SaveResult, error)
- func SetLogout(ctx context.Context, secureStorage bool) (SaveResult, error)
- func SetToken(ctx context.Context, token string, secureStorage bool) (SaveResult, error)
- type State
- func (s *State) CheckedExtensionUpdateAt(binaryName string) time.Time
- func (s *State) CheckedForUpdateAt() time.Time
- func (s *State) LatestRelease() Release
- func (s *State) SetCheckedExtensionUpdateAt(binaryName string, t time.Time)
- func (s *State) SetCheckedForUpdateAt(t time.Time)
- func (s *State) SetLatestRelease(r Release)
- type TokenStorage
Constants ¶
const ( // DefaultHost is the CircleCI API host used when none is configured. DefaultHost = "https://circleci.com" // DefaultExtensionHost is the CircleCI extension host. DefaultExtensionHost = "https://circleci-binary-releases.s3.amazonaws.com" )
const DefaultTheme = "auto"
DefaultTheme is the color theme used when none is configured. It matches the default of the --theme flag and detects the terminal background.
Variables ¶
This section is empty.
Functions ¶
func ActiveTelemetryOverrides ¶
func ActiveTelemetryOverrides() []string
ActiveTelemetryOverrides returns the names of environment variables that are currently set and override the stored telemetry preference.
func ExtensionsDir ¶
ExtensionsDir returns the absolute path to the extensions directory, following the XDG Base Directory spec:
- $XDG_DATA_HOME/circleci/extensions (when XDG_DATA_HOME is set)
- ~/.local/share/circleci/extensions (default)
func LockPath ¶ added in v1.0.47519
LockPath returns the advisory-lock companion path for a config or state file (path + ".lock"). Exported so callers outside this package can take the same lock LoadState / SaveState use — e.g. tests that pre-acquire it.
func SaveState ¶ added in v1.0.47519
SaveState performs a locked read-modify-write of the state file at path: it loads the current state (zero if absent) under an exclusive advisory lock, passes it to mutate, then writes the result back. This mirrors the read-modify-write Config uses for its own writes, so the whole read → mutate → write is atomic against other circleci invocations.
func SetHost ¶
SetHost persists the CircleCI server host. The host is not a secret, so it is always written to the config file and never touches secure storage (passing secureStorage here would make saveTo delete the keyring token).
func SetTelemetry ¶
SetTelemetry persists the telemetry opt-in/opt-out preference. path follows the same convention as Load (empty → XDG default).
func SetTheme ¶
SetTheme persists the color theme preference. The theme is not a secret, so it is always written to the config file and never touches secure storage (passing secureStorage here would make saveTo delete the keyring token). Validation of the value is the caller's responsibility (see iostream.IsValidTheme).
func SetUpdateCheck ¶ added in v1.0.47519
SetUpdateCheck persists the update-notification opt-in/opt-out preference. path follows the same convention as Load (empty → XDG default).
func StateDir ¶ added in v1.0.47519
StateDir returns the absolute path to the CLI state directory. Resolution mirrors the GitHub CLI's config.StateDir (github.com/cli/go-gh), in priority order:
- $XDG_STATE_HOME/circleci (when XDG_STATE_HOME is set, any platform)
- %LocalAppData%\circleci (Windows — LocalAppData, not roaming AppData, because state is machine-local bookkeeping that should not roam)
- ~/.local/state/circleci (default)
State is machine-managed bookkeeping (e.g. the last update-check timestamp), deliberately kept out of config.yml so it never churns a file users hand-edit.
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config holds all persisted CLI settings.
func Load ¶
Load reads the config file from the given path. If path is empty the default XDG path is used. Returns an empty Config if the file does not exist.
func (*Config) EffectiveExtensionHost ¶
EffectiveExtensionHost returns the host, checked in priority order: CIRCLE_HOST env var → config file value → DefaultHost.
func (*Config) EffectiveHost ¶
EffectiveHost returns the host, checked in priority order: CIRCLE_HOST env var → config file value → DefaultHost.
func (*Config) EffectiveTheme ¶
EffectiveTheme returns the configured color theme, or DefaultTheme when none has been set.
func (*Config) EffectiveToken ¶
EffectiveToken returns the token from the config, falling back to the CIRCLE_TOKEN environment variable (with CIRCLE_CLI_TOKEN as a legacy alias).
func (*Config) IsTelemetry ¶
IsTelemetry returns true when telemetry should be collected. Environment variables always take precedence over the stored config value. When no preference has been set, telemetry is enabled by default.
func (*Config) IsUpdateCheck ¶ added in v1.0.47519
IsUpdateCheck reports whether the CLI may check for a newer release. The CIRCLE_NO_UPDATE_CHECK environment variable always takes precedence over the stored config value. When no preference has been set, checks are enabled.
type Release ¶ added in v1.0.47519
type Release struct {
Version string `yaml:"version,omitempty"`
PublishedAt time.Time `yaml:"published_at,omitempty"`
}
Release is the newest release recorded by the last successful update check.
type SaveResult ¶
type SaveResult struct {
// Storage is where the token actually landed.
Storage TokenStorage
// KeyringErr is non-nil when secure storage was requested but the OS keyring
// could not be used, so the token transparently fell back to the config
// file. It wraps keyring.ErrUnavailable (and may be keyring.ErrAccessDenied
// for a denial the user can fix, such as an unconnected snap interface).
// This is NOT a fatal error — callers may inspect it to surface guidance.
KeyringErr error
}
SaveResult reports the outcome of a token-mutating call.
func DeleteToken ¶
func DeleteToken(ctx context.Context, secureStorage bool) (SaveResult, error)
DeleteToken removes the stored API token from both the config file and the system keyring (when secure storage is in use).
func SetLogin ¶
func SetLogin(ctx context.Context, path, host, token string, userID uuid.UUID, secureStorage bool) (SaveResult, error)
SetLogin persists the host, token, and user ID to path, or to the default XDG location when path is empty.
Honouring path matters because the caller reports it as the save location and may re-read it afterwards; writing elsewhere makes both the message and the re-read describe a file that was never written.
type State ¶ added in v1.0.47519
type State struct {
// contains filtered or unexported fields
}
State holds the CLI's machine-managed bookkeeping, persisted to state.yml. Unlike Config it is never hand-edited — it records things the CLI tracks for itself, such as when it last checked for a newer release. Read it with LoadState and mutate it with SaveState; both take the same advisory lock the config read-modify-write uses, so concurrent circleci invocations (parallel shells, CI matrices, an agent firing several commands) can't corrupt it.
func LoadState ¶ added in v1.0.47519
LoadState reads the state file at path under a shared advisory lock, mirroring the lock Config's read path takes. A missing file yields a zero State. path is required (callers pass StatePath()).
func (*State) CheckedExtensionUpdateAt ¶ added in v1.0.48210
CheckedExtensionUpdateAt reports when the registry was last queried for a newer version of the named extension.
func (*State) CheckedForUpdateAt ¶ added in v1.0.47519
CheckedForUpdateAt reports when the last update check refreshed from the network. The zero value means no check has ever succeeded.
func (*State) LatestRelease ¶ added in v1.0.47519
LatestRelease returns the newest release the last update check saw.
func (*State) SetCheckedExtensionUpdateAt ¶ added in v1.0.48210
SetCheckedExtensionUpdateAt records when the named extension was last checked against the registry.
func (*State) SetCheckedForUpdateAt ¶ added in v1.0.47519
SetCheckedForUpdateAt records when an update check last refreshed.
func (*State) SetLatestRelease ¶ added in v1.0.47519
SetLatestRelease records the newest release seen (pass the zero Release to clear it).
type TokenStorage ¶
type TokenStorage int
TokenStorage reports where a token-mutating call actually persisted (or removed from) the token, so callers can print an accurate location. When secure storage is requested but the OS keyring is unavailable, the call transparently falls back to the config file and reports StoredInFile.
const ( // StoredInFile means the token was written to (or cleared from) the // plaintext config file — either because --insecure-storage was set, or // because secure storage was requested but the keyring was unavailable. StoredInFile TokenStorage = iota // StoredInKeyring means the token was written to (or removed from) the OS // keyring. StoredInKeyring )
Source Files