repos

package
v0.29.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 6, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package repos provides reusable per-repo installation logic for fullsend. It decouples the core install flow (guard check, WIF provisioning, 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

This section is empty.

Variables

View Source
var ErrMintNotFound = errors.New("mint function not found")

ErrMintNotFound indicates the mint function does not exist.

View Source
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 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.

Types

type DefaultsConfig

type DefaultsConfig struct {
	InferenceProject       string   `yaml:"inference_project"`
	InferenceRegion        string   `yaml:"inference_region"`
	FullsendRef            string   `yaml:"fullsend_ref"`
	BaseHarness            string   `yaml:"base_harness"`
	AllowedRemoteResources []string `yaml:"allowed_remote_resources"`
}

DefaultsConfig holds default field values applied to every repo unless overridden at the per-repo level.

type InstallConfig

type InstallConfig struct {
	Owner string
	Repo  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
	SkipMintCheck  bool
	SkipWIF        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 a pre-provisioned WIF provider resource name. When set
	// and SkipWIF is true, the install skips WIF provisioning and uses this
	// value directly.
	WIFProvider string

	VendorBinary bool

	// Direct controls scaffold delivery: true pushes directly to the default
	// branch; false creates a PR.
	Direct bool
}

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, provisioner WIFProvisioner,
	commitScaffold ScaffoldCommitFunc,
	progress ProgressFunc) (*InstallResult, error)

Install performs a per-repo fullsend installation. It checks for an existing installation, optionally discovers mint infrastructure and provisions WIF, generates and commits scaffold files, and writes repository variables and secrets.

The commitScaffold callback handles scaffold file delivery. The CLI layer provides an implementation with retry and fallback semantics; tests provide a simple fake.

CLI concerns (prompts, spinners, token resolution, scope checks, dry-run) are handled by the caller. This function contains only the pure install logic.

type Manifest

type Manifest struct {
	Version  int            `yaml:"version"`
	Mint     MintConfig     `yaml:"mint"`
	Defaults DefaultsConfig `yaml:"defaults"`
	Repos    []RepoEntry    `yaml:"repos"`
}

Manifest is the top-level structure of a repos.yaml file.

func LoadManifest

func LoadManifest(ctx context.Context, pathOrURL string) (*Manifest, error)

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) ExpandGlobs

func (m *Manifest) ExpandGlobs(ctx context.Context, client forge.Client) ([]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 excludes private, archived, and forked repositories. Private repos must be listed as explicit entries in the manifest until the forge interface is extended (see implementation plan).

func (*Manifest) Marshal

func (m *Manifest) Marshal() ([]byte, error)

Marshal serializes the manifest back to YAML.

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:

  1. Per-repo override (from RepoEntry)
  2. Manifest defaults (from DefaultsConfig)
  3. 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) Validate

func (m *Manifest) Validate() error

Validate checks the manifest for structural correctness:

  • version must be 1
  • mint.url must be a valid HTTPS URL
  • mint.project and mint.region must be non-empty
  • 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

type MintConfig

type MintConfig struct {
	URL     string `yaml:"url"`
	Project string `yaml:"project"`
	Region  string `yaml:"region"`
}

MintConfig holds the mint service connection parameters.

type MintDiscovery

type MintDiscovery struct {
	URL             string
	RoleAppIDs      map[string]string
	PerRepoWIFRepos []string
}

MintDiscovery holds the results of a mint infrastructure discovery call.

type NullableString

type NullableString struct {
	Value string
	Set   bool
	Null  bool
}

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", "wif", "scaffold", "vars")
  • message: a human-readable status message

type RepoEntry

type RepoEntry struct {
	Repo             string         `yaml:"repo"`
	InferenceProject NullableString `yaml:"inference_project,omitempty"`
	InferenceRegion  NullableString `yaml:"inference_region,omitempty"`
	FullsendRef      NullableString `yaml:"fullsend_ref,omitempty"`
	BaseHarness      NullableString `yaml:"base_harness,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) UnmarshalYAML

func (r *RepoEntry) UnmarshalYAML(node *yaml.Node) error

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 ResolvedConfig

type ResolvedConfig struct {
	Owner                  string
	Repo                   string
	MintURL                string
	MintProject            string
	MintRegion             string
	InferenceProject       string
	InferenceRegion        string
	FullsendRef            string
	BaseHarness            string
	AllowedRemoteResources []string
}

ResolvedConfig is the fully resolved configuration for a single repository after merging per-repo overrides, manifest defaults, and built-in defaults.

type ResolvedRepo

type ResolvedRepo struct {
	Owner string
	Repo  string
	Entry RepoEntry
}

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 WIFProvisioner

type WIFProvisioner interface {
	// DiscoverMint fetches mint infrastructure info (URL, role-to-app-ID
	// mappings, per-repo WIF repos). Returns an error wrapping
	// ErrMintNotFound if the mint function does not exist.
	DiscoverMint(ctx context.Context) (*MintDiscovery, error)

	// ProvisionWIF creates WIF infrastructure (service account, pool,
	// provider, principal binding) and returns the full WIF provider
	// resource name.
	ProvisionWIF(ctx context.Context) (string, error)

	// RegisterPerRepoWIF adds a repo to the mint's PER_REPO_WIF_REPOS
	// env var so the mint routes OIDC tokens for that repo to a dedicated
	// WIF provider.
	RegisterPerRepoWIF(ctx context.Context, repo string) error

	// EnsureOrgInMint validates that a mint function exists at expectedURL
	// and that the given org is registered in ALLOWED_ORGS.
	EnsureOrgInMint(ctx context.Context, expectedURL string, org string) error

	// DeletePerRepoWIF removes a repo from per-repo WIF registration.
	DeletePerRepoWIF(ctx context.Context, repo string) error
}

WIFProvisioner abstracts Workload Identity Federation and mint discovery operations, decoupling the install logic from the concrete GCF provisioner.

All methods return wrapped errors suitable for errors.Is checks. DiscoverMint wraps ErrMintNotFound when the mint function does not exist. Other methods return provider-specific errors (e.g., IAM permission denied).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL