Configuration¶

Every value forge reads, where it comes from, what it defaults to, and what happens when it is wrong.

Per-provider keys are listed with each provider in providers; this page covers the shared surface and gathers the environment variables in one place.

Which configuration surfaces exist¶

Three, and they are deliberately separate. Confusing them is the most common reason a value appears to be ignored.

forge reads no configuration file, no environment variable and no flag on its own. It reads the keys you hand it, from the Config you hand it. Precedence lives in your configuration stack. See authenticate.

What goes in an Endpoint¶

type Endpoint struct {
    Type string
    Host string
    Name string
}

Every field is connection identity. What a provider operates on (an owner, a repository) is a parameter of the operation, and lives on the method that needs it rather than on the address.

Endpoint is comparable, which is the point: a consumer reusing providers can key on it directly rather than deriving a hash from a wider struct.

Which options exist¶

A nil passed to any of them is ignored rather than treated as an instruction to unset, and WithHTTPTransport ignores a typed nil too. An http.RoundTripper holding a nil *http.Transport is not equal to nil, and would otherwise panic at the first request rather than at the call that introduced it.

Which configuration key holds the credential¶

const DefaultAuthKey = "auth.value"

forge.ConfigCredential(cfg, "") reads DefaultAuthKey. Any other key you pass is read verbatim against whatever Config you hand in. There is no scoping rule, so both of these work:

forge.ConfigCredential(sub, "")                          // gitlab.auth.value, via Sub
forge.ConfigCredential(root, "platforms.gitlab.token")   // your own layout

Keys this module no longer reads¶

auth.env and auth.keychain were rungs of a resolution ladder that has been removed. They are reported rather than ignored, because configuration that looks correct and yields no credential fails later as an unexplained 401.

ErrStaleAuthKeys is not fatal on its own. FirstCredential retains it and returns it only when nothing else produced a credential, so a stale key sitting beside a working environment variable stays quiet.

forge-bitbucket removed its equivalents the same way: bitbucket.username.env and bitbucket.app_password.env are no longer read and are reported as stale.

Which environment variables forge reads¶

The core module reads none. forge.EnvCredential(name) reads whatever variable you name, and an empty name reads nothing rather than guessing.

The well-known fallbacks below are constants declared by each provider module and composed into its default credential source. They are consulted last, after the configured key.

A provider composing this default is doing it in its config adapter, in the open. Set Settings.Credential and you replace the whole composition, environment fallback included.

Which configuration keys the direct provider accepts¶

direct has no API to ask, so everything it needs comes from its configuration subtree: direct for the default source, direct.<name> for a named one. Keys not listed here are ignored.

Configure neither pinned_version nor version_url and GetLatestRelease returns direct.ErrVersionUnknown. Assuming a version silently would be worse.

Placeholders in a direct template¶

The same expansion applies to all three templates.

{ext} does not vary. There is no .zip branch, so a source publishing Windows archives as .zip has to write the extension into the template literally.

What the size bounds default to¶

Every bounded read takes the limit as a parameter: the caller owns the policy, the provider enforces it. These constants are suggested values, not mandates.

One bound is not yours to choose: the direct provider caps its version endpoint response at 1 MiB internally, and no param changes it.

How a factory reads them¶

forge.NewOptions(opts...) normalises the set, so a factory can use Options.Logger without a nil check, and can test Options.HTTPTransport and Options.HTTPClient for nil to decide which rung it was handed.

What happens when a value is wrong¶

Related¶

• Providers: per-provider keys and capabilities
• Errors: every sentinel and what to do with it
• Authenticate to a forge: composing credential sources
• Log what a provider does: the logging option in full