Documentation
¶
Overview ¶
Package repos provides reusable per-repo installation logic for fullsend. It decouples the core install flow (guard check, scaffold commit, variable/secret writes) from CLI concerns (prompts, spinners, flag parsing) so that both the interactive CLI and future bulk-install commands can share the same logic.
Package repos implements parsing, validation, and resolution of the repos.yaml declarative manifest that drives multi-repo management (ADR 0057).
Index ¶
- Constants
- Variables
- func AddToManifest(ctx context.Context, cfg ManifestEditConfig, entries []RepoEntry, ...) (*ManifestAddResult, *Manifest, error)
- func BuildScaffoldFiles(cfg InstallConfig) ([]forge.TreeFile, error)
- func FormatDiffTable(result *DiffResult) string
- func IsNumeric(s string) bool
- func IsValidForge(name string) bool
- func IsValidGCPProjectID(s string) bool
- func IsValidGCPRegion(s string) bool
- func IsValidRef(ref string) bool
- func MarshalWithHeader(m *Manifest) ([]byte, error)
- func MatchManifestRepos(manifest *Manifest, patterns []string) ([]string, error)
- func RemoveFromManifest(cfg ManifestEditConfig, repos []string, progress ProgressFunc) (*ManifestRemoveResult, *Manifest, error)
- func ScaffoldPathsForForge(forgeName string) []string
- func SetDefault(manifestPath, key, value string) error
- func UninstallSecretsForForge(forgeName string) []string
- func UninstallVarsForForge(forgeName string) []string
- type BatchInstallConfig
- type BatchInstallResult
- type Change
- type DefaultsConfig
- type DiffResult
- type DiscoveredRepo
- type Drift
- type FailedRepo
- type ForgeClientFactory
- type ForgeConfig
- type ForgeSection
- type GitHubForgeInfra
- type GitLabForgeInfra
- type InferenceProvisioner
- type InstallConfig
- type InstallResult
- type Manifest
- func (m *Manifest) DistinctForges() []string
- func (m *Manifest) ExpandGlobs(ctx context.Context, clients ForgeClientFactory) ([]ResolvedRepo, error)
- func (m *Manifest) HasForge(name string) bool
- func (m *Manifest) Marshal() ([]byte, error)
- func (m *Manifest) ResolveConfig(owner, repo string) (ResolvedConfig, bool)
- func (m *Manifest) ResolveConfigForEntry(owner, repo string, entry RepoEntry) ResolvedConfig
- func (m *Manifest) ResolveConfigWithGlobs(owner, repo string) (ResolvedConfig, bool)
- func (m *Manifest) Validate() error
- type ManifestAddResult
- type ManifestEditConfig
- type ManifestRemoveResult
- type MigrateConfig
- type MigrateRepoResult
- type MigrateResult
- type MintRegistrar
- type NullableString
- type ProgressFunc
- type RepoEntry
- type RepoState
- type RepoStatus
- type ResolvedConfig
- type ResolvedRepo
- type ScaffoldCommitFunc
- type StatusResult
- type StatusSummary
- type SyncResult
- type UninstallConfig
- type UninstallResult
- type UpgradeConfig
- type UpgradeResult
Constants ¶
const ( ForgeGitHub = "github" ForgeGitLab = "gitlab" )
Forge type constants used in the manifest's forge field.
const DefaultGitHubURL = "https://github.com"
DefaultGitHubURL is the default forge URL for GitHub.com.
Variables ¶
var ValidDefaultKeys = []string{
"defaults.allowed_remote_resources",
"forge.github.url",
"forge.github.mint_url",
"forge.github.fullsend_ref",
"forge.gitlab.url",
"forge.gitlab.runner_tags",
}
ValidDefaultKeys lists the manifest keys that can be set via `repos set-default`. Order matches the help text.
var WIFProviderPattern = regexp.MustCompile(
`^projects/\d+/locations/global/workloadIdentityPools/[a-z][a-z0-9-]{2,30}[a-z0-9]/providers/[a-z][a-z0-9-]{2,30}[a-z0-9]$`,
)
WIFProviderPattern validates the full WIF provider resource name format required by google-github-actions/auth@v3. GCP pool/provider IDs: 4-32 chars, [a-z0-9-], start with letter, no trailing hyphen.
Functions ¶
func AddToManifest ¶ added in v0.32.0
func AddToManifest(ctx context.Context, cfg ManifestEditConfig, entries []RepoEntry, clients ForgeClientFactory, progress ProgressFunc) (*ManifestAddResult, *Manifest, error)
AddToManifest appends repo entries to the manifest, skipping duplicates. When client is non-nil, each non-glob repo is probed for existing installation state and per-repo overrides are populated where the discovered values differ from manifest defaults. Returns the result and the modified manifest. The manifest is written to disk only when ManifestPath is set and DryRun is false.
func BuildScaffoldFiles ¶
func BuildScaffoldFiles(cfg InstallConfig) ([]forge.TreeFile, error)
BuildScaffoldFiles generates the scaffold tree files for a per-repo install. Exported so the CLI dry-run path can display the file list without running the full install.
func FormatDiffTable ¶ added in v0.32.0
func FormatDiffTable(result *DiffResult) string
FormatDiffTable renders a DiffResult as a human-readable table.
func IsValidForge ¶ added in v0.33.0
IsValidForge reports whether the given forge name is supported.
func IsValidGCPProjectID ¶ added in v0.34.0
IsValidGCPProjectID checks that s matches the GCP project ID format: 6-30 characters, lowercase letters, digits, and hyphens, starting with a letter.
func IsValidGCPRegion ¶ added in v0.34.0
IsValidGCPRegion checks that s looks like a GCP region: lowercase letters, digits, and hyphens (e.g. "us-central1", "europe-west4").
func IsValidRef ¶ added in v0.32.0
IsValidRef reports whether ref contains only characters safe for use in GitHub Actions workflow uses: lines.
func MarshalWithHeader ¶ added in v0.31.0
MarshalWithHeader serializes the manifest with a descriptive header comment.
func MatchManifestRepos ¶ added in v0.32.0
MatchManifestRepos returns the list of repo names from the manifest that match any of the given patterns. Used by CLI commands to resolve positional args (which may contain globs) against manifest entries.
func RemoveFromManifest ¶ added in v0.32.0
func RemoveFromManifest(cfg ManifestEditConfig, repos []string, progress ProgressFunc) (*ManifestRemoveResult, *Manifest, error)
RemoveFromManifest removes matching repo entries from the manifest. Patterns containing glob characters (*, ?, [) are matched against manifest entries using filepath.Match. Returns the result and the modified manifest.
func ScaffoldPathsForForge ¶ added in v0.34.0
ScaffoldPathsForForge returns the scaffold file paths to delete for the given forge during uninstall.
func SetDefault ¶ added in v0.34.0
SetDefault sets or removes a forge-level default in the manifest. An empty value removes the key. The file is created with version: 1 if it does not exist.
func UninstallSecretsForForge ¶ added in v0.34.0
UninstallSecretsForForge returns the CI/CD secret names to delete for the given forge during uninstall.
func UninstallVarsForForge ¶ added in v0.34.0
UninstallVarsForForge returns the CI/CD variable names to delete for the given forge during uninstall.
Types ¶
type BatchInstallConfig ¶ added in v0.31.0
type BatchInstallConfig struct {
Manifest *Manifest
DryRun bool
RepoFilter []string
MaxConcurrency int
// Roles is the list of agent roles to install (e.g., "triage", "coder").
Roles []string
// UpstreamRef is the git ref (SHA) used to pin scaffold workflow refs.
UpstreamRef string
// UpstreamTag is the version tag corresponding to UpstreamRef.
UpstreamTag string
// Direct controls scaffold delivery: true pushes directly to the default
// branch; false creates a PR.
Direct bool
// InferenceProject is the GCP project ID for inference. This is an
// install-time-only value passed via CLI flag, not stored in the
// manifest. Written as the FULLSEND_GCP_PROJECT_ID repo secret.
InferenceProject string
// InferenceProjectNumber is the numeric GCP project number used
// to compute the WIF provider resource name. Install-time-only,
// not stored in the manifest.
InferenceProjectNumber string
// InferenceRegion is the GCP region for inference. Install-time-only,
// not stored in the manifest.
InferenceRegion string
}
BatchInstallConfig holds all inputs for a multi-repo install operation.
type BatchInstallResult ¶ added in v0.31.0
type BatchInstallResult struct {
Installed []InstallResult
Skipped []InstallResult
Failed []InstallResult
}
BatchInstallResult holds the outcome of a multi-repo install operation.
func BatchInstall ¶ added in v0.31.0
func BatchInstall(ctx context.Context, cfg BatchInstallConfig, clients ForgeClientFactory, commitScaffold ScaffoldCommitFunc, progress ProgressFunc) (*BatchInstallResult, error)
BatchInstall provisions fullsend on multiple repos from a manifest.
It runs in two phases:
- Parallel discovery: check guard variables to partition repos into toInstall and alreadyInstalled.
- Parallel scaffold: commit scaffold files and write variables/secrets for each repo that passes validation.
The WIF provider resource name is computed deterministically from inference_project_number + BuildRepoProviderID(owner, repo). No GCP API calls are made.
Errors on individual repos do not abort the batch.
type Change ¶ added in v0.32.0
type Change struct {
Owner string `json:"owner"`
Repo string `json:"repo"`
Field string `json:"field"`
Type string `json:"type"` // "variable" or "secret"
Action string `json:"action"` // "create" or "update"
OldValue string `json:"old_value,omitempty"` // empty for secrets (not readable)
NewValue string `json:"new_value,omitempty"` // empty for secrets
}
Change describes a single field that needs to be updated to reconcile a repo's actual state with the manifest's desired state.
type DefaultsConfig ¶
type DefaultsConfig struct {
Forge string `yaml:"forge"`
AllowedRemoteResources []string `yaml:"allowed_remote_resources,omitempty"`
}
DefaultsConfig holds default field values applied to every repo.
type DiffResult ¶ added in v0.32.0
type DiffResult struct {
Changes []Change `json:"changes"`
Warnings []string `json:"warnings,omitempty"`
}
DiffResult holds the output of a diff operation.
func Diff ¶ added in v0.32.0
func Diff(ctx context.Context, manifest *Manifest, clients ForgeClientFactory, maxConcurrency int, repoFilter []string) (*DiffResult, error)
Diff compares the manifest's desired state against the actual forge state and returns a list of changes needed to reconcile. Only examines repos that are already installed (guard variable is "true"); uninstalled repos are reported as warnings.
For secrets, Diff only reports missing secrets (action "create") because secret values cannot be read back for comparison.
type DiscoveredRepo ¶ added in v0.31.0
type DiscoveredRepo struct {
Owner string
Repo string
Source string // "per-repo", "per-org", or "new"
MintURL string
InferenceRegion string
FullsendRef string
}
DiscoveredRepo holds the result of discovering a single repo's fullsend installation status.
type Drift ¶ added in v0.31.0
type Drift struct {
Field string `json:"field"`
Expected string `json:"expected"`
Actual string `json:"actual"`
}
Drift describes a single field that differs between the manifest's desired state and the repo's actual state.
type FailedRepo ¶ added in v0.34.0
SyncResult holds the output of a sync operation. FailedRepo identifies a repo that failed sync.
type ForgeClientFactory ¶ added in v0.33.0
type ForgeClientFactory interface {
// ConfigFor returns a ForgeConfig with a live Client for the named forge.
// The factory lazily creates and caches clients, so a GitLab token is
// only required if the manifest actually contains GitLab entries.
ConfigFor(forgeName string) (ForgeConfig, error)
}
ForgeClientFactory creates ForgeConfig instances with a live Client. The CLI layer implements this with lazy client creation and caching.
type ForgeConfig ¶ added in v0.33.0
type ForgeConfig struct {
// Client is the API client for this forge. Set by ForgeClientFactory;
// nil when ForgeConfig is constructed by ForgeConfigFor (pattern-only).
Client forge.Client
// WorkflowPaths lists the shim workflow file paths to try, in order.
WorkflowPaths []string
// WorkflowRefPattern extracts the @ref from a fullsend shim workflow.
WorkflowRefPattern *regexp.Regexp
// ShimRefPattern matches all @ref occurrences in fullsend uses: lines
// within a workflow file, used by upgrade to rewrite refs.
ShimRefPattern *regexp.Regexp
}
ForgeConfig holds forge-specific CI paths and regex patterns used by status and upgrade operations. Each forge has different workflow file conventions and ref syntax. When populated by a ForgeClientFactory, the Client field carries a live API client for the forge.
func ForgeConfigFor ¶ added in v0.33.0
func ForgeConfigFor(forgeName string) ForgeConfig
ForgeConfigFor returns the ForgeConfig for the given forge name. Unknown values (including empty string) default to GitHub. This is intentional: callers in legacy code paths may pass an empty forge, and Validate() catches invalid forge names before they reach here.
func GitHubForgeConfig ¶ added in v0.33.0
func GitHubForgeConfig() ForgeConfig
GitHubForgeConfig returns the ForgeConfig for GitHub repositories. GitHub Actions workflow files live under .github/workflows/ and use the "uses: owner/repo/.github/workflows/file@ref" syntax.
func GitLabForgeConfig ¶ added in v0.33.0
func GitLabForgeConfig() ForgeConfig
GitLabForgeConfig returns the ForgeConfig for GitLab repositories. GitLab CI files live under .gitlab/ci/ and use include: directives with ref: fields. Patterns here are placeholders for the GitLab CI dispatch template structure (see ADR 0067). The ShimRefPattern matches any ref: line in the file — the dispatch file must contain only the fullsend include (single-include constraint).
type ForgeSection ¶ added in v0.33.0
type ForgeSection struct {
GitHub GitHubForgeInfra `yaml:"github,omitempty"`
GitLab GitLabForgeInfra `yaml:"gitlab,omitempty"`
}
ForgeSection holds per-forge infrastructure configuration. Each key maps a forge name to its infrastructure settings. Only forges actually referenced by repos in the manifest need entries here.
func ForgeSectionFromURL ¶ added in v0.33.0
func ForgeSectionFromURL(forgeName, forgeURL string) ForgeSection
ForgeSectionFromURL constructs a ForgeSection with only the URL field populated for the named forge. Used when no full manifest is available (e.g. repos migrate).
type GitHubForgeInfra ¶ added in v0.33.0
type GitHubForgeInfra struct {
URL string `yaml:"url,omitempty"`
MintURL string `yaml:"mint_url,omitempty"`
FullsendRef string `yaml:"fullsend_ref,omitempty"`
}
GitHubForgeInfra holds GitHub-specific infrastructure settings for the token mint service and inference configuration.
GCP project ID and project number are sensitive install-time-only values passed via CLI flags to `repos install`. They are NOT stored in the manifest.
type GitLabForgeInfra ¶ added in v0.33.0
type GitLabForgeInfra struct {
URL string `yaml:"url"`
RunnerTags []string `yaml:"runner_tags,omitempty"`
}
GitLabForgeInfra holds GitLab-specific infrastructure settings.
type InferenceProvisioner ¶ added in v0.34.0
type InferenceProvisioner interface {
// Status checks if WIF infrastructure is already provisioned for a repo.
// Returns the WIF provider resource name if provisioned, empty string
// if not.
Status(ctx context.Context, owner, repo string) (wifProvider string, err error)
// Provision creates WIF infrastructure for a repo and returns the WIF
// provider resource name.
Provision(ctx context.Context, owner, repo string) (wifProvider string, err error)
}
InferenceProvisioner abstracts GCP WIF infrastructure operations. CLI implementations call real GCP APIs; tests provide stubs.
type InstallConfig ¶
type InstallConfig struct {
Owner string
Repo string
Forge string
// Roles is the list of agent roles to install (e.g., "triage", "code").
Roles []string
MintURL string
InferenceProject string
InferenceRegion string
// UpstreamRef is the git ref (SHA) used to pin scaffold workflow refs.
// Empty for dev builds (falls back to config.DefaultUpstreamRef).
UpstreamRef string
// UpstreamTag is the version tag corresponding to UpstreamRef (e.g., "v0.42.0").
UpstreamTag string
// Skip flags control which install steps are executed. Set by callers
// that handle specific steps externally (e.g., admin.go handles guard
// checks and mint setup before calling Install).
SkipAppSetup bool
SkipGuardCheck bool
// SkipScaffoldAndConfig skips scaffold file delivery and variable/secret
// writes. The caller handles these steps externally (e.g., vendor mode
// commits scaffold and vendor files together atomically).
SkipScaffoldAndConfig bool
// WIFProvider is the pre-computed WIF provider resource name. The caller
// is responsible for computing or provisioning this value before calling
// Install. Required unless SkipScaffoldAndConfig is true.
WIFProvider string
// PerRepoConfig, when set, overrides the default per-repo config
// generated by NewPerRepoConfig. Used during migration to carry
// over org config fields into the per-repo config.
PerRepoConfig config.PerRepoConfigWriter
VendorBinary bool
// RunnerTags is a list of GitLab CI runner tags to embed in scaffold
// pipeline YAML so that agent jobs are routed to specific runners.
RunnerTags []string
// Direct controls scaffold delivery: true pushes directly to the default
// branch; false creates a PR.
Direct bool
// ReuseSecrets indicates that GCP secrets (FULLSEND_GCP_PROJECT_ID and
// FULLSEND_GCP_WIF_PROVIDER) already exist on the repo and should not
// be overwritten. When true, InferenceProject and WIFProvider may be
// empty and secret writes are skipped.
ReuseSecrets bool
// DiscoveredCredMode is the existing FULLSEND_CREDENTIAL_MODE value
// read from the repo during discovery. Used to preserve the credential
// mode on re-install when InferenceProject is not provided.
DiscoveredCredMode string
}
InstallConfig is a pure data struct holding all inputs needed for a per-repo installation. CLI flags, environment variables, and interactive prompts are resolved by the caller before constructing this struct.
type InstallResult ¶
type InstallResult struct {
Owner string
Repo string
Success bool
Error error
AlreadyInstalled bool
// WIFProvider is the WIF provider resource name, either pre-existing
// (from InstallConfig) or newly provisioned.
WIFProvider string
}
InstallResult holds the outcome of a per-repo installation.
func Install ¶
func Install(ctx context.Context, cfg InstallConfig, client forge.Client, commitScaffold ScaffoldCommitFunc, progress ProgressFunc) (*InstallResult, error)
Install performs a per-repo fullsend installation. It checks for an existing installation, generates and commits scaffold files, and writes repository variables and secrets. The caller is responsible for computing the WIF provider resource name (via InstallConfig.WIFProvider) before calling this function — GCP provisioning is handled separately by `inference provision` and `mint enroll`.
type Manifest ¶
type Manifest struct {
Version int `yaml:"version"`
Forge ForgeSection `yaml:"forge"`
Defaults DefaultsConfig `yaml:"defaults"`
Repos []RepoEntry `yaml:"repos"`
}
Manifest is the top-level structure of a repos.yaml file.
func LoadManifest ¶
LoadManifest reads and parses a repos.yaml manifest from a local file path or an HTTPS URL. Remote fetches enforce a 30-second timeout and a 1 MB response size limit.
func (*Manifest) DistinctForges ¶ added in v0.33.0
DistinctForges returns the deduplicated set of forge names actually used by entries in the manifest, after resolving per-entry overrides against defaults. Only forges referenced by at least one repo entry are included. The order is deterministic (sorted).
func (*Manifest) ExpandGlobs ¶
func (m *Manifest) ExpandGlobs(ctx context.Context, clients ForgeClientFactory) ([]ResolvedRepo, error)
ExpandGlobs resolves wildcard repo entries by listing org repos via the forge API (requires network access). Explicit entries always win over glob-matched entries. The returned list is deduplicated and sorted.
ListOrgRepos is called with includePrivate=true because repos.yaml manifests are used in per-repo mode, where agents run on the target repo itself. Archived and forked repos remain excluded.
The clients factory provides per-forge API clients so glob entries targeting different forges resolve against the correct API.
func (*Manifest) HasForge ¶ added in v0.33.0
HasForge reports whether any repo in the manifest resolves to the given forge name.
func (*Manifest) ResolveConfig ¶
func (m *Manifest) ResolveConfig(owner, repo string) (ResolvedConfig, bool)
ResolveConfig computes the fully merged configuration for the given owner/repo by looking up the entry in the manifest's repo list. The resolution order is:
- Per-repo override (from RepoEntry)
- Manifest defaults (from DefaultsConfig)
- Built-in defaults (empty strings)
An explicit null at any level stops the fallback chain, returning "". The second return value indicates whether the repo was found in the manifest's repo list. When false, the returned config uses only manifest defaults and built-in values.
For repos matched via glob expansion, use ResolveConfigForEntry instead — this method only finds exact matches in the manifest's repo list and will not match glob patterns.
func (*Manifest) ResolveConfigForEntry ¶
func (m *Manifest) ResolveConfigForEntry(owner, repo string, entry RepoEntry) ResolvedConfig
ResolveConfigForEntry computes the fully merged configuration for the given owner/repo using the provided RepoEntry. Use this with entries returned by ExpandGlobs, which carry per-glob overrides that ResolveConfig cannot find by exact match.
func (*Manifest) ResolveConfigWithGlobs ¶ added in v0.33.0
func (m *Manifest) ResolveConfigWithGlobs(owner, repo string) (ResolvedConfig, bool)
ResolveConfigWithGlobs resolves config for a repo, falling back to glob-pattern matching when the exact entry lookup fails.
func (*Manifest) Validate ¶
Validate checks the manifest for structural correctness:
- version must be 1
- forge.github.url defaults to https://github.com when unset; mint_url is required when at least one repo resolves to forge: github
- forge.gitlab.url is required when at least one repo resolves to forge: gitlab
- each repo entry must have a valid owner/repo or owner/glob format
- glob characters are only allowed in the repo name, not the owner
- no duplicate repo entries (before glob expansion)
- glob patterns must be valid filepath.Match patterns
- forge URLs must be valid HTTPS URLs with no path component
type ManifestAddResult ¶ added in v0.32.0
ManifestAddResult holds the outcome of adding repos to a manifest.
type ManifestEditConfig ¶ added in v0.32.0
ManifestEditConfig holds inputs for manifest add/remove operations.
type ManifestRemoveResult ¶ added in v0.32.0
ManifestRemoveResult holds the outcome of removing repos from a manifest.
type MigrateConfig ¶ added in v0.34.0
type MigrateConfig struct {
// Org is the GitHub organization to migrate.
Org string
// Project is the GCP project ID for inference (required).
Project string
// RepoFilter limits migration to specific repos (supports globs).
RepoFilter []string
// DryRun previews changes without applying.
DryRun bool
// Direct pushes scaffold directly to the default branch instead of
// creating a PR.
Direct bool
// MaxConcurrency is the parallel limit for per-repo operations.
MaxConcurrency int
// ManifestPath is the output path for the generated repos.yaml.
ManifestPath string
// Roles is the list of agent roles to install.
Roles []string
// UpstreamRef is the git ref (SHA) used to pin scaffold workflow refs.
UpstreamRef string
// UpstreamTag is the version tag corresponding to UpstreamRef.
UpstreamTag string
// CLIVersion is the current CLI version, used for manifest ref defaults.
CLIVersion string
}
MigrateConfig holds configuration for the repos migrate command.
type MigrateRepoResult ¶ added in v0.34.0
type MigrateRepoResult struct {
Owner string
Repo string
Status string // "migrated", "skipped", "failed"
WIFProvider string
Error error
StatusError error
}
MigrateRepoResult holds the outcome of migrating a single repo.
type MigrateResult ¶ added in v0.34.0
type MigrateResult struct {
Migrated []MigrateRepoResult
Skipped []MigrateRepoResult
Failed []MigrateRepoResult
Manifest *Manifest
Unenrolled int
UnenrollError error
}
MigrateResult holds the overall outcome of a migration.
func Migrate ¶ added in v0.34.0
func Migrate(ctx context.Context, cfg MigrateConfig, clients ForgeClientFactory, provisioner InferenceProvisioner, mintReg MintRegistrar, commitScaffold ScaffoldCommitFunc, progress ProgressFunc) (*MigrateResult, error)
Migrate orchestrates the full migration of an org from per-org to per-repo install. For each enrolled repo it:
- Checks if already per-repo installed (skips if so)
- Checks/provisions inference WIF infrastructure
- Installs per-repo (scaffold, variables, secrets)
- Unenrolls from per-org config
At the end, it generates a repos.yaml manifest from the discovered state. Individual repo failures do not abort the batch.
type MintRegistrar ¶ added in v0.34.0
type MintRegistrar interface {
// RegisterPerRepoWIF adds a repo to the mint's PER_REPO_WIF_REPOS
// environment variable. The repo must be in "owner/repo" format.
RegisterPerRepoWIF(ctx context.Context, repo string) error
}
MintRegistrar abstracts mint enrollment for per-repo WIF. CLI implementations call real GCP APIs to add repos to PER_REPO_WIF_REPOS; tests provide stubs.
type NullableString ¶
NullableString distinguishes three YAML states: omitted (zero value), explicit null (Set=true, Null=true), and an explicit string value (Set=true, Null=false, Value holds the string). This three-state design lets per-repo overrides explicitly clear a default with "field: null" rather than inheriting it.
A fourth state — Set=true, Value="" (explicit empty string in YAML) — is treated as unset by resolveField and falls through to defaults. This matches the ADR spec: "Empty-string and zero-value overrides are treated as unset and fall through to defaults."
func (NullableString) IsZero ¶
func (n NullableString) IsZero() bool
IsZero reports whether n was never set, used by the YAML encoder to honor the omitempty tag.
func (NullableString) MarshalYAML ¶
func (n NullableString) MarshalYAML() (interface{}, error)
MarshalYAML serializes a NullableString back to YAML, preserving the null vs omitted distinction.
func (*NullableString) UnmarshalYAML ¶
func (n *NullableString) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML decodes a YAML scalar into a NullableString, treating the !!null tag as an explicit null.
type ProgressFunc ¶
type ProgressFunc func(repo, phase, message string)
ProgressFunc is a callback for reporting installation progress. The caller maps this to spinner output, structured logs, or whatever UI is appropriate.
Parameters:
- repo: the "owner/repo" being installed
- phase: a machine-readable phase name (e.g., "guard", "scaffold", "vars", "secrets")
- message: a human-readable status message
type RepoEntry ¶
type RepoEntry struct {
Repo string `yaml:"repo"`
Forge NullableString `yaml:"forge,omitempty"`
// Per-repo override fields. These use the NullableString 3-level
// fallback chain: per-repo → forge default → built-in default.
// Explicit null stops the chain. Omitted fields inherit the
// forge-level default.
FullsendRef NullableString `yaml:"fullsend_ref,omitempty"`
MintURL NullableString `yaml:"mint_url,omitempty"`
// AllowedRemoteResources overrides the defaults.allowed_remote_resources
// list. A non-nil slice replaces the default; nil (omitted) inherits.
AllowedRemoteResources []string `yaml:"allowed_remote_resources,omitempty"`
}
RepoEntry represents a single repo or glob pattern in the manifest. It supports two YAML forms: a plain string ("acme/repo") or an object with optional per-repo overrides.
func (RepoEntry) MarshalYAML ¶ added in v0.34.0
MarshalYAML serializes a RepoEntry back to YAML, preserving both the plain-string form (when no overrides are set) and the explicit-null semantics for AllowedRemoteResources.
func (*RepoEntry) UnmarshalYAML ¶
UnmarshalYAML handles both string and mapping YAML forms. It manually walks the mapping node to correctly detect !!null values on NullableString fields, since yaml.v3's struct decoder skips calling UnmarshalYAML for null-tagged scalars.
type RepoState ¶ added in v0.32.0
RepoState holds the installation state of a single repo as read from forge variables and workflow files.
func ProbeRepoState ¶ added in v0.32.0
func ProbeRepoState(ctx context.Context, client forge.Client, owner, repo string, fc ForgeConfig) (RepoState, error)
ProbeRepoState reads a repo's current per-repo installation state from forge variables and workflow files.
type RepoStatus ¶ added in v0.31.0
type RepoStatus struct {
Owner string `json:"owner"`
Repo string `json:"repo"`
Installed bool `json:"installed"`
CurrentRef string `json:"current_ref,omitempty"`
ExpectedRef string `json:"expected_ref,omitempty"`
MintURL string `json:"mint_url,omitempty"`
ExpectedMintURL string `json:"expected_mint_url,omitempty"`
Region string `json:"region,omitempty"`
Drifts []Drift `json:"drifts,omitempty"`
Error string `json:"error,omitempty"`
}
RepoStatus holds the status of a single repo as compared against the manifest's desired state.
type ResolvedConfig ¶
type ResolvedConfig struct {
Owner string
Repo string
Forge string
ForgeConfig ForgeConfig
MintURL string
FullsendRef string
AllowedRemoteResources []string
}
ResolvedConfig is the fully resolved configuration for a single repository after merging manifest defaults and forge-level settings. The ForgeConfig field carries per-forge patterns and (when populated by ForgeClientFactory.ConfigFor) a live API client.
type ResolvedRepo ¶
ResolvedRepo pairs an owner/repo with the manifest entry that matched it (either an explicit entry or a glob-generated one).
type ScaffoldCommitFunc ¶
type ScaffoldCommitFunc func(ctx context.Context, owner, repo string, files []forge.TreeFile, direct bool) error
ScaffoldCommitFunc delivers scaffold files to a repository and returns any error encountered.
The CLI layer provides an implementation wrapping layers.CommitScaffoldFiles, which adds retry on non-fast-forward errors, branch-protection fallback to PR delivery, and fork-based PR support for non-owner users.
type StatusResult ¶ added in v0.31.0
type StatusResult struct {
Repos []RepoStatus `json:"repos"`
Summary StatusSummary `json:"summary"`
Warnings []string `json:"warnings,omitempty"`
}
StatusResult holds the full output of a status check.
func Status ¶ added in v0.31.0
func Status(ctx context.Context, manifest *Manifest, clients ForgeClientFactory, maxConcurrency int, repoFilter []string) (*StatusResult, error)
Status compares the manifest's desired state against the actual forge state for each repo. It returns a StatusResult with per-repo status and aggregate counts. API calls are parallelised up to maxConcurrency.
type StatusSummary ¶ added in v0.31.0
type StatusSummary struct {
Total int `json:"total"`
Installed int `json:"installed"`
NotInstalled int `json:"not_installed"`
Drifted int `json:"drifted"`
Errored int `json:"errored"`
}
StatusSummary provides aggregate counts across all repos. Counts are not mutually exclusive: a repo can be both Installed and Errored (e.g. guard variable set but workflow read fails), so Installed + NotInstalled + Errored may exceed Total.
type SyncResult ¶ added in v0.32.0
type SyncResult struct {
Applied []Change `json:"applied"`
Failed int `json:"failed,omitempty"`
FailedRepos []FailedRepo `json:"failed_repos,omitempty"`
Warnings []string `json:"warnings,omitempty"`
}
func Sync ¶ added in v0.32.0
func Sync(ctx context.Context, manifest *Manifest, clients ForgeClientFactory, maxConcurrency int, repoFilter []string, progress ProgressFunc) (*SyncResult, error)
Sync reconciles configuration drift for installed repos by applying variable changes to match the manifest's desired state. Variables are only written when drift is detected. Secrets are written once at install time and are not reconciled by sync.
Sync does NOT touch scaffold shim version (@ref) or harness files. Version changes are handled by the upgrade phase of repos install.
type UninstallConfig ¶ added in v0.32.0
UninstallConfig holds all inputs for a multi-repo uninstall operation.
type UninstallResult ¶ added in v0.32.0
type UninstallResult struct {
Owner string
Repo string
Success bool
Error error
WorkflowDeleted bool
VarsDeleted int
SecretsDeleted int
}
UninstallResult holds the outcome of uninstalling fullsend from a single repo.
func Uninstall ¶ added in v0.32.0
func Uninstall(ctx context.Context, cfg UninstallConfig, clients ForgeClientFactory, progress ProgressFunc) ([]UninstallResult, error)
Uninstall tears down fullsend from the specified repos.
It runs in a single phase: parallel per-repo cleanup (bounded by MaxConcurrency) deletes the workflow file, then deletes variables and secrets.
GCP WIF cleanup is handled separately via `inference deprovision`.
Does NOT modify repos.yaml — use RemoveFromManifest for that.
type UpgradeConfig ¶ added in v0.32.0
type UpgradeConfig struct {
Manifest *Manifest
RefOverride string
RepoFilter []string
DryRun bool
Force bool
Direct bool
MaxConcurrency int
}
UpgradeConfig holds configuration for a batch upgrade operation.
type UpgradeResult ¶ added in v0.32.0
type UpgradeResult struct {
Owner string
Repo string
OldRef string
NewRef string
Upgraded bool
Skipped bool
SkipReason string
Error error
}
UpgradeResult holds the outcome of upgrading a single repo.
func Upgrade ¶ added in v0.32.0
func Upgrade(ctx context.Context, cfg UpgradeConfig, clients ForgeClientFactory, commitFn ScaffoldCommitFunc, progress ProgressFunc) ([]UpgradeResult, error)
Upgrade upgrades the scaffold shim ref across repos in the manifest. It reads each repo's current workflow file, determines whether an upgrade is needed, and commits the updated workflow with the new ref.