README
¶
VCS
GTB's config adapters for the standalone gitlab.com/phpboyscout/go/forge (release
providers, credential chain) and gitlab.com/phpboyscout/go/repo (git operations)
modules. The forge clients themselves (GitHub, GitLab, Gitea/Codeberg, Bitbucket)
live in the external go/forge-<name> modules, blank-imported by the binary that
ships them.
Package structure
- repo: props/config adapters for the
go/repomodule. - config_adapter.go: adapts a GTB config view to the
forge.Configseam. - credential.go: composes GTB's forge credential chain (
auth.env→auth.keychain→auth.value→ the well-known fallback env var) and hands it to a provider factory throughforge.WithCredential.
For the full picture, see the VCS component documentation.
Documentation
¶
Overview ¶
Package vcs holds the thin configuration adapters that bridge GTB's resolved configuration to the extracted version-control modules.
The forge backends themselves no longer live here. Release querying and the provider registry are the standalone module gitlab.com/phpboyscout/go/forge (with per-provider adapters forge-github, forge-gitlab, forge-gitea, forge-bitbucket, plus the built-in direct source); repository cloning and metadata are gitlab.com/phpboyscout/go/repo. What remains in this package is GTB-side glue:
- ConfigFromReader adapts a GTB config.Reader to the narrow forge.Config seam the provider factories consume, and CredentialOptions hands a factory GTB's credential chain (ForgeCredential) so it composes none of its own.
- the repo sub-package's config adapter maps GTB props/config to go/repo Settings.
These adapters stay in GTB because they encode GTB's config-key layout and credential-resolution conventions, which are not the modules' concern.
Index ¶
Constants ¶
const ( // OriginNone means no rung produced a credential. OriginNone = credentialposture.OriginNone // OriginEnvRef is {forge}.auth.env, dereferenced. OriginEnvRef = credentialposture.OriginEnvRef // OriginKeychain is {forge}.auth.keychain, dereferenced. OriginKeychain = credentialposture.OriginKeychain // OriginLiteral is the {forge}.auth.value literal. OriginLiteral = credentialposture.OriginLiteral // OriginFallbackEnv is the well-known fallback variable (e.g. GITHUB_TOKEN). OriginFallbackEnv = credentialposture.OriginFallbackEnv )
const ConfigKeyProvider = "vcs.provider"
ConfigKeyProvider overrides the release-source forge a tool was built with.
Variables ¶
This section is empty.
Functions ¶
func ConfigFromReader ¶ added in v0.32.0
ConfigFromReader adapts GTB's resolved configuration to the forge config reader a provider factory takes. Hand it the ROOT configuration; the factory scopes it to the endpoint's section itself.
func CredentialOptions ¶ added in v0.43.0
func CredentialOptions(endpoint forge.Endpoint, cfg forge.Config, fallbackEnv string) []forge.Option
CredentialOptions hands a provider factory GTB's credential chain for the endpoint's section of cfg, so the factory consults it and nothing else (go/forge spec 0025 D2, spec 0026): auth.env and auth.keychain are dereferenced by GTB, never read by the factory, and the construction context bounds the resolution. cfg is the ROOT configuration, as the factory receives it.
A single-token forge gets its chain through forge.WithCredential and no username; a factory ignores forge.WithUsername it has no use for. Bitbucket authenticates with two halves, so it gets both: the username through forge.WithUsername and the app password through forge.WithCredential, each walking its own env-reference and literal keys and the one keychain entry that holds both, read once.
func ForgeCredential ¶ added in v0.36.0
func ForgeCredential(sub forge.Config, fallbackEnv string) forge.CredentialSource
ForgeCredential composes the credential chain for one forge over an already-scoped config reader.
sub is the forge's subtree — vcs.ConfigFromReader(cfg).Sub("github") — so the per-forge namespacing is stated by the Sub and never repeated in a key literal here. A nil sub (absent section) is not an error: the environment fallback still applies, which is what lets a tool be configured purely by environment.
Every rung is lazy. Nothing is read, and no keychain is touched, until the returned source is called — so a repository authenticating over SSH never triggers an unlock prompt for a token it does not need.
Types ¶
type CredentialOrigin ¶ added in v0.36.0
type CredentialOrigin = credentialposture.Origin
CredentialOrigin names the rung that supplied a credential. It is an alias for the general vocabulary in pkg/credentialposture rather than a second copy: forges and AI providers report the same facts, and two enumerations that mean the same thing eventually disagree. Spec 0189 D4.
func ResolveForgeCredentialOrigin ¶ added in v0.36.0
func ResolveForgeCredentialOrigin( ctx context.Context, sub forge.Config, fallbackEnv string, ) (CredentialOrigin, error)
ResolveForgeCredentialOrigin reports WHICH rung supplies a forge's credential, without returning the credential itself.
It exists so a diagnostic can tell an operator that their configuration resolves, and from where, without printing a secret to a terminal or a support bundle. "It resolves, from auth.env" and "nothing resolves" are the two facts worth having, and neither needs the value.
The walk itself lives in pkg/credentialposture, shared with every other credential GTB reports on. Error handling is that package's: a rung that fails does not stop the walk, because a later rung may still supply a working credential — and the retained error is returned only when nothing resolved, which is exactly when a bare "no credential" would otherwise hide the reason.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package repo adapts GTB's runtime configuration into the typed settings used by the standalone gitlab.com/phpboyscout/go/repo module.
|
Package repo adapts GTB's runtime configuration into the typed settings used by the standalone gitlab.com/phpboyscout/go/repo module. |