README
¶
VCS
Abstractions for Version Control System operations, supporting multiple backends like GitHub and GitLab.
Package Structure
- github: GitHub-specific client and release implementation.
- gitlab: GitLab release provider implementation.
- repo: Generic Git repository management (Local and In-memory).
- release: Domain interfaces for releases, assets, and providers.
Pluggable Release Providers
The VCS package provides a release.Provider interface that abstracts release operations across different platforms:
- Programmatic API interaction (PRs, releases, etc.)
- Unified authentication layer for SSH and tokens
- Backend-agnostic asset downloads
For detailed documentation, testing strategies, and configuration options, see the Version Control Component Documentation.
Documentation
¶
Overview ¶
Package vcs defines the version-control abstraction layer for querying releases and repository metadata across multiple forge backends.
The release-source registry supports GitHub, GitLab, Bitbucket, Gitea/Forgejo/Codeberg, and a direct-HTTP source. Sub-packages provide the concrete implementations (github, gitlab, bitbucket, gitea, direct), release for the pluggable provider registry and factory, and repo for repository URL parsing and metadata extraction.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConfigFromContainable ¶ added in v0.30.0
func ConfigFromContainable(cfg config.Containable) release.Config
ConfigFromContainable adapts GTB's config container to the narrow VCS release config reader used by release providers.
func ResolveToken ¶
func ResolveToken(cfg TokenConfig, fallbackEnv string) string
ResolveToken resolves an authentication token from a config subtree.
Resolution order:
- cfg.auth.env — NAME of an environment variable to read
- cfg.auth.keychain — "<service>/<account>" reference in the OS keychain; active only when the process has imported pkg/credentials/keychain (or otherwise registered a backend). Silently skipped when no backend is registered or when the keychain is unreachable at the time of the call.
- cfg.auth.value — literal token value stored in config. Viper's AutomaticEnv + tool prefix also surfaces <TOOL>_AUTH_VALUE style env vars via this step.
- fallbackEnv — well-known unprefixed environment variable (pass "" to skip).
Returns an empty string when no token is found; callers decide whether that is an error condition (e.g. private repositories require a token, public repositories can proceed without one).
The callers-supplied `cfg` is typically `props.Config.Sub("<vcs>")` — GTB's env-aware Sub ensures prefix-aware env binding fires even inside sub-containers (see pkg/config).
ResolveToken uses context.Background when calling the keychain backend. Callers who have a request context (HTTP handler, cobra command, chat provider) SHOULD use ResolveTokenContext instead so a slow remote backend (Vault, SSM) cannot stall the caller beyond its own deadline.
func ResolveTokenContext ¶
func ResolveTokenContext(ctx context.Context, cfg TokenConfig, fallbackEnv string) string
ResolveTokenContext is the context-aware form of ResolveToken. The context is propagated to the credentials backend so remote stores honour deadlines and cancellation. Recommended for any call path that already has a context in scope.
Types ¶
type AuthConfig ¶ added in v0.30.0
type AuthConfig struct {
Env string `mapstructure:"env" json:"env" yaml:"env"`
Value string `mapstructure:"value" json:"value" yaml:"value"`
Keychain string `mapstructure:"keychain" json:"keychain" yaml:"keychain"`
}
AuthConfig is the typed auth shape shared by VCS providers. It still satisfies TokenConfig so existing token-resolution semantics are reused.
func (AuthConfig) GetString ¶ added in v0.30.0
func (cfg AuthConfig) GetString(key string) string
type TokenConfig ¶ added in v0.30.0
TokenConfig is the minimal string lookup surface needed for VCS token resolution.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bitbucket provides a release.Provider implementation for Bitbucket Cloud using the Downloads API.
|
Package bitbucket provides a release.Provider implementation for Bitbucket Cloud using the Downloads API. |
|
Package direct provides a release.Provider implementation for tools distributed via arbitrary HTTP servers.
|
Package direct provides a release.Provider implementation for tools distributed via arbitrary HTTP servers. |
|
Package gitea provides a release.Provider implementation for Gitea and Forgejo instances, including Codeberg (codeberg.org).
|
Package gitea provides a release.Provider implementation for Gitea and Forgejo instances, including Codeberg (codeberg.org). |
|
Package github implements the VCS release provider and API client for GitHub repositories, supporting both public and token-authenticated access.
|
Package github implements the VCS release provider and API client for GitHub repositories, supporting both public and token-authenticated access. |
|
Package gitlab implements the VCS release provider for GitLab repositories, supporting both public and token-authenticated access; the owner may be a slash-separated group path passed through to the GitLab API.
|
Package gitlab implements the VCS release provider for GitLab repositories, supporting both public and token-authenticated access; the owner may be a slash-separated group path passed through to the GitLab API. |
|
Package release provides the shared release abstractions (Release, ReleaseAsset) and a pluggable Provider registry and factory.
|
Package release provides the shared release abstractions (Release, ReleaseAsset) and a pluggable Provider registry and factory. |
|
releasetest
Package releasetest provides an in-memory release.Provider test double and asset builders for exercising the self-update pipeline without network or disk access.
|
Package releasetest provides an in-memory release.Provider test double and asset builders for exercising the self-update pipeline without network or disk access. |
|
Package repo provides git repository operations (clone, checkout, commit, push, tree inspection) backed by go-git, behind the RepoLike abstraction with local-filesystem and in-memory storage backends.
|
Package repo provides git repository operations (clone, checkout, commit, push, tree inspection) backed by go-git, behind the RepoLike abstraction with local-filesystem and in-memory storage backends. |
|
aferobilly
Package aferobilly adapts a go-billy/v5 Filesystem to an afero.Fs.
|
Package aferobilly adapts a go-billy/v5 Filesystem to an afero.Fs. |