Skip to content

Authenticate to a forge

Credentials are resolved through one chain, shared by every provider, so a consumer configures them the same way regardless of which forge is behind the interface.

The chain

ResolveToken walks four tiers and takes the first non-empty result:

Order Source Config key Notes
1 Environment reference auth.env Names a variable; the value is read from it
2 OS keychain auth.keychain service/account
3 Literal value auth.value Weakest — a secret in a config file
4 Well-known fallback — The provider's TokenFallbackEnv, e.g. GITHUB_TOKEN 
token := forge.ResolveToken(settings.Auth, settings.TokenFallbackEnv)

The ordering is deliberate: an explicit reference beats an implicit fallback, and a literal is last among the configured options because it is the one that ends up committed to a repository by accident.

Wiring it up

settings.Auth = forge.AuthConfig{
    Env:      sub.GetString("auth.env"),
    Value:    sub.GetString("auth.value"),
    Keychain: sub.GetString("auth.keychain"),
}

AuthConfig satisfies TokenConfig, so it can be passed straight to ResolveToken. If your configuration lives somewhere else entirely, implement TokenConfig yourself — it is one method.

Pin the credential before you send it

Resolving a token is half the job. Attaching it only to the host you authenticated against is the other half:

if token != "" && forge.HostTrusted(assetURL, p.baseURL) {
    req.Header.Set("Authorization", "token "+token)
}

Asset URLs come from release metadata, which a release author controls. See credential pinning for the threat model — this is the single easiest way to leak a token from an otherwise-correct provider.

No credential is often fine

A missing token is not automatically an error. Public releases download unauthenticated, and rate limits are usually the only difference. Decide the policy at the layer that knows whether the repository is private, and fail fast there with a message naming the variable to set — rather than letting an unauthenticated request fail later with an opaque 404.