Documentation
¶
Overview ¶
Package repos provides reusable per-repo installation logic for fullsend. It decouples the core install flow (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, forgeName string, ...) (*ManifestAddResult, *Manifest, error)
- func AllMatch(components []ComponentStatus) bool
- func AppendGitLabPipelineRefStatus(ctx context.Context, client forge.Client, owner, repo string, userIDs []int, ...) bool
- func BuildScaffoldFiles(cfg InstallConfig) ([]forge.TreeFile, error)
- func DriftFieldName(componentName string) string
- func EnrichGitLabRoleStatus(ctx context.Context, client forge.Client, owner, repo string, ...) bool
- func ExpectedScaffoldContent(ctx context.Context, resolved ResolvedConfig, dcfg DriftConfig, ...) ([]forge.TreeFile, error)
- func FetchRemoteScaffold(ctx context.Context, ghClient forge.Client, ...) (scaffold.InstallFiles, error)
- func GitLabPATExpiresAt(now time.Time) string
- func GitLabPipelineVarRestrictionEnforced() bool
- func HasFullsendEntries(existing []byte) bool
- func IsGitLabRoleManagedVar(name string) bool
- 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 LoadGitLabRoleState(ctx context.Context, client forge.Client, owner, repo string) (gitlabroles.Registry, map[string]bool, error)
- func LockGitLabRoleOperation(owner, repo string) func()
- func MarshalWithHeader(m *Manifest) ([]byte, error)
- func MatchManifestRepos(manifest *Manifest, patterns []string) ([]string, error)
- func MergeGitLabCI(existing []byte) ([]byte, error)
- func MergeMissingGitLabDebugTraceRule(existing []byte) (result []byte, changed bool, err error)
- func PollerCanCreatePipeline(rule *forge.ProtectedBranchRule, userIDs []int) bool
- func PollerPipelineUserIDs(tokens []ProjectAccessToken) []int
- func RejectExtraneousURLParts(u *url.URL, field string) error
- func RemoveFromManifest(cfg ManifestEditConfig, repos []string, progress ProgressFunc) (*ManifestRemoveResult, *Manifest, error)
- func RuntimeSection(runtime string) string
- func ScaffoldPathsForForge(forgeName string) []string
- func SetDefault(manifestPath, key, value string) error
- func StripObsoleteGitLabStages(existing []byte) (result []byte, changed bool, err error)
- func StripObsoleteGitLabWorkflowRules(existing []byte) (result []byte, changed bool, err error)
- func UninstallSecretsForForge(forgeName string) []string
- func UninstallVarsForForge(forgeName string) []string
- func UnmergeGitLabCI(existing []byte) ([]byte, error)
- func UpdateAppSet(cfg ManifestEditConfig, filters []string, appSet string) ([]string, error)
- func ValidateAllowedRemoteResourcesFormat(field string, list []string) error
- type ComponentAction
- type ComponentStatus
- type ConfigBase
- type ContentDriftFile
- type ConvergeBatchResult
- type ConvergeConfig
- type ConvergeResult
- type DefaultsConfig
- type DiscoveredRepo
- type Drift
- type DriftConfig
- type ForgeClientFactory
- type ForgeConfig
- type GitLabPipelineAccessResult
- type GitLabPipelineVarRestrictionResult
- type GitLabRoleCleanupConfig
- type GitLabRoleCleanupResult
- type InferenceProvisioner
- type InstallConfig
- type InstallResult
- type ManagedVar
- type Manifest
- func (m *Manifest) AllRepos() []RepoEntry
- func (m *Manifest) DistinctForges() []string
- func (m *Manifest) DistinctForgesFor(filter []string) ([]string, error)
- func (m *Manifest) EnsurePlatform(forgeName string) *PlatformConfig
- func (m *Manifest) ExpandGlobs(ctx context.Context, clients ForgeClientFactory) ([]ResolvedRepo, error)
- func (m *Manifest) ExpandGlobsFor(ctx context.Context, clients ForgeClientFactory, filter []string) ([]ResolvedRepo, error)
- func (m *Manifest) HasForge(name string) bool
- func (m *Manifest) LayeredConfig(entry RepoEntry, baseYAML []byte) (config.PerRepoConfigReader, error)
- func (m *Manifest) Marshal() ([]byte, error)
- func (m *Manifest) PlatformFor(forgeName string) *PlatformConfig
- func (m *Manifest) RenderManagedConfig(entry RepoEntry) (data []byte, ok bool, err error)
- func (m *Manifest) ResolveConfig(owner, repo string) (ResolvedConfig, bool)
- func (m *Manifest) ResolveConfigForEntry(owner, repo, forgeName string, entry RepoEntry) ResolvedConfig
- func (m *Manifest) ResolveConfigWithGlobs(owner, repo string) (ResolvedConfig, bool)
- func (m *Manifest) TotalRepoCount() int
- func (m *Manifest) Validate() error
- type ManifestAddResult
- type ManifestEditConfig
- type ManifestRemoveResult
- type MigrateConfig
- type MigrateRepoResult
- type MigrateResult
- type OrphanFile
- type OrphanVar
- type PlatformConfig
- type ProgressFunc
- type ProjectAccessToken
- type ProjectAccessTokenClient
- type RefResolver
- type RepoEntry
- type RepoState
- type RepoStatus
- type ResolvedConfig
- type ResolvedRepo
- type RoleProvisionConfig
- type RoleProvisionFailure
- type RoleProvisionResult
- type RoleRotateConfig
- type RoleRotateResult
- type ScaffoldCommitFunc
- type ScaffoldMetadataOpts
- type ScaffoldPRMetadata
- type ScheduleSpec
- type StatusResult
- type StatusSummary
- type UninstallConfig
- type UninstallResult
Constants ¶
const ( ForgeGitHub = "github" ForgeGitLab = "gitlab" )
Forge type constants used in the manifest's platform sections.
const ( MintModePublic = "public" MintModePrivate = "private" DefaultPublicMintURL = "https://mint.fullsend.sh" )
Mint mode constants control the default mint URL for GitHub repos.
const ( // DefaultScaffoldBranch is the branch name for fresh installations. It // is also reused for uninstall PR delivery (see UninstallPRMetadata) // since already-deployed per-repo shims only exclude this branch name // from triggering the fullsend dispatch job. DefaultScaffoldBranch = "fullsend/scaffold-install" // ScaffoldBumpBranchPrefix is the branch prefix for version upgrades. ScaffoldBumpBranchPrefix = "fullsend/bump-" )
const ActionAdoptionRequired = "adoption-required"
ActionAdoptionRequired marks a ComponentAction reporting that an existing managed .fullsend/config.yaml predates ADR-0122 adoption (missing the ownership marker) and was therefore left untouched. It is deliberately distinct from "none" so convergeRepo's hasAction check below still counts a pending adoption as outstanding work instead of classifying the repo AlreadyCurrent.
const ActionSafetyRejected = "safety-rejected"
ActionSafetyRejected marks a ComponentAction reporting that the candidate managed configuration is less restrictive than the current effective configuration and the manifest did not declare that relaxation (ADR 0122). Distinct from "error" so status/adoption output can identify the affected keys without treating a parse failure as the same class of problem.
const DefaultGitHubURL = "https://github.com"
DefaultGitHubURL is the default forge URL for GitHub.com.
const GitLabPipelineVarRestrictionEnv = "FULLSEND_GITLAB_PIPELINE_VAR_RESTRICTION"
GitLabPipelineVarRestrictionEnv gates whether install/converge actively enforces ci_pipeline_variables_minimum_override_role=owner on enrolled GitLab repos (#7769). Defaulting to unset/report-only reflects that raising the poller/dispatcher identity to Owner-level access — needed so the restriction does not also block the poller's own API-triggered dispatch pipeline, see internal/repos/gitlab_pipeline_access.go and internal/poll/dispatch.go — is an explicit, not-yet-made credential- cost decision (ADR 0125 Status/Caveats). Set to "enforced" once that follow-up ships.
const NoneSentinel = "none"
NoneSentinel is the YAML value that explicitly clears an inherited field in the override cascade. Use "fullsend_ref: none" in YAML to stop the per-repo → platform-default → built-in-default chain.
Variables ¶
var ValidDefaultKeys = []string{
"defaults.allowed_remote_resources",
"defaults.runtime",
"defaults.vendor",
"defaults.config_base.source",
"defaults.config_base.sha256",
"github.url",
"github.mint_url",
"github.mint_mode",
"github.fullsend_ref",
"gitlab.url",
"gitlab.fullsend_ref",
"gitlab.agent_runner_tags",
"gitlab.control_runner_tags",
"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, forgeName string, entries []RepoEntry, clients ForgeClientFactory, progress ProgressFunc) (*ManifestAddResult, *Manifest, error)
AddToManifest appends repo entries to the appropriate platform section, skipping duplicates. The forgeName parameter determines which platform section receives the entries. 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 platform defaults. Returns the result and the modified manifest. The manifest is written to disk only when ManifestPath is set and DryRun is false.
func AllMatch ¶ added in v0.37.0
func AllMatch(components []ComponentStatus) bool
AllMatch returns true when every ComponentStatus has Match == true.
func AppendGitLabPipelineRefStatus ¶ added in v0.44.0
func AppendGitLabPipelineRefStatus(ctx context.Context, client forge.Client, owner, repo string, userIDs []int, status *RepoStatus) bool
AppendGitLabPipelineRefStatus reports drift when the poller cannot create pipelines on the protected default branch. Returns true when a new drift entry was added. Missing repo metadata or unsupported forges are skipped rather than failing the whole status check.
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 DriftFieldName ¶ added in v0.37.0
DriftFieldName returns the component name without its category prefix, suitable for use as a Drift.Field value. "var:FULLSEND_MINT_URL" becomes "FULLSEND_MINT_URL"; "workflow" stays "workflow".
func EnrichGitLabRoleStatus ¶ added in v0.44.0
func EnrichGitLabRoleStatus(ctx context.Context, client forge.Client, owner, repo string, tokens []ProjectAccessToken, now time.Time, status *RepoStatus) bool
EnrichGitLabRoleStatus re-runs DiagnoseLifecycle with a token inventory so repos status can report expiry, revocation, and overlapping replacements. tokens may be nil. It reports whether any lifecycle drift entries were newly added to status.Drifts; callers must not assume a false return means the repo is otherwise free of drift, only that this call did not add to it.
func ExpectedScaffoldContent ¶ added in v0.38.0
func ExpectedScaffoldContent(ctx context.Context, resolved ResolvedConfig, dcfg DriftConfig, refResolver *RefResolver) ([]forge.TreeFile, error)
ExpectedScaffoldContent renders the scaffold files that a fresh install would produce for the given resolved config. The status path uses this to compare against installed files for content drift detection — when the rendered template differs from the installed file, the repo's scaffold is stale even if the ref string matches.
When fullsend_ref pins a version that differs from the running binary, the refResolver fetches remote scaffold templates from the pinned ref so the baseline matches the pinned version, not the embedded templates. This mirrors the converge path's FetchRemoteScaffold logic. Both paths share driftInstallConfig as the underlying input builder and BuildScaffoldFiles as the renderer.
Returns (nil, nil) when FullsendRef is empty — there is no expected ref to compare against.
func FetchRemoteScaffold ¶ added in v0.37.0
func FetchRemoteScaffold(ctx context.Context, ghClient forge.Client, manifestRef, resolvedSHA, forgeName string, agentRunnerTags, controlRunnerTags []string, vendored bool, ) (scaffold.InstallFiles, error)
FetchRemoteScaffold fetches scaffold templates from fullsend-ai/fullsend at the given ref and renders them for the specified forge. This is used when fullsend_ref pins to a version that differs from the running binary, so embedded templates would be incorrect.
Callers should skip this function when vendored is true: the running binary's embedded templates already match the binary being committed to the repo, so there is no version-skew concern and the remote fetch would add unnecessary API latency.
Template paths (scaffoldGitHubShimPath, scaffoldGitLabPaths) are pinned to the current binary's layout. If the remote ref reorganises these paths, the fetch fails gracefully and the caller falls back to embedded templates — cross-version compatibility is best-effort.
func GitLabPATExpiresAt ¶ added in v0.44.0
GitLabPATExpiresAt returns the YYYY-MM-DD expiry GitLab expects for a project access token. GitLab evaluates expires_at in UTC.
func GitLabPipelineVarRestrictionEnforced ¶ added in v0.44.0
func GitLabPipelineVarRestrictionEnforced() bool
GitLabPipelineVarRestrictionEnforced reports whether install/converge should actively set ci_pipeline_variables_minimum_override_role=owner, as opposed to only reporting drift against that target.
func HasFullsendEntries ¶ added in v0.38.0
HasFullsendEntries reports whether existing .gitlab-ci.yml content already contains all fullsend CI entries. It performs semantic drift detection by checking:
- include: contains the fullsend-pipeline.yml entry
- If stages: exists, it contains poll, agent (if no stages: key, the included pipeline provides them). The obsolete "dispatch" stage is not required (#7337).
- If workflow: exists, it must have a rules: sequence containing fullsend's if: conditions. If workflow: exists without rules:, that is drift — MergeGitLabCI would add them. (if no workflow: block at all, fullsend's jobs self-filter)
Used by the installer to skip unnecessary .gitlab-ci.yml writes when all entries are already present, avoiding YAML formatting churn.
func IsGitLabRoleManagedVar ¶ added in v0.44.0
IsGitLabRoleManagedVar reports whether a FULLSEND_* CI/CD variable is a GitLab role-credential artifact (registry, built-in or custom role secret), or the legacy shared token. This is an orphan-detection classification only: it tells drift/orphan scans that the name is recognized role-identity state, not an unmanaged leftover. It does not mean the variable is removed on uninstall — the legacy FULLSEND_FORGE_TOKEN shared token is deliberately excluded from automatic uninstall cleanup (see gitLabRoleUninstallVars and extraGitLabRoleUninstallVars) and requires manual cleanup.
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 LoadGitLabRoleState ¶ added in v0.44.0
func LoadGitLabRoleState(ctx context.Context, client forge.Client, owner, repo string) (gitlabroles.Registry, map[string]bool, error)
LoadGitLabRoleState reads the registered role policy and per-secret presence from a repository. Migration state is deliberately not read.
func LockGitLabRoleOperation ¶ added in v0.44.0
func LockGitLabRoleOperation(owner, repo string) func()
LockGitLabRoleOperation serializes role credential operations for one repo.
func MarshalWithHeader ¶ added in v0.31.0
MarshalWithHeader serializes the manifest with a descriptive header comment. Like Manifest.Marshal, it does not mutate the receiver — the deprecated runner_tags migration runs against a shallow copy.
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 MergeGitLabCI ¶ added in v0.38.0
MergeGitLabCI merges fullsend's CI configuration into an existing .gitlab-ci.yml. It uses yaml.v3's Node API to preserve comments and formatting in the existing file.
The merge performs up to three operations:
- Appends an include entry for .gitlab/ci/fullsend-pipeline.yml (skipped if already present)
- Appends fullsend's current stages (poll, agent) to the existing stages: array, deduplicating if already present. Skipped when no stages: key exists. Does not add the obsolete "dispatch" stage (#7337).
- When a workflow: block already exists, merges workflow:rules entries (deduplicates by if: condition) and sets auto_cancel.on_new_commit: none if not present. When no workflow: block exists, it is left absent so the repo's push-triggered pipelines are not disrupted.
When existing is nil or empty, returns a minimal .gitlab-ci.yml with just the fullsend include and workflow block.
func MergeMissingGitLabDebugTraceRule ¶ added in v0.44.0
MergeMissingGitLabDebugTraceRule adds fullsend's CI_DEBUG_TRACE deny-before-admit workflow rule (ADR 0125) to an existing .gitlab-ci.yml when it is missing, leaving everything else — including any already-present fullsend rules, the workflow name, auto_cancel settings, and any user configuration — untouched.
This backfills already-enrolled repos: MergeGitLabCI (and the debug-trace rule it adds via fullsendWorkflowRules) only runs on fresh installs — the install call site skips it once HasFullsendEntries is true — and the periodic converge/upgrade path does not otherwise touch workflow:rules. Without this, a repo enrolled before this rule existed would never pick it up, leaving a debug-trace pipeline able to reach an admit rule and dump secrets at job init.
The rule is only merged when gitlabCIWorkflowIsFullsendOwned finds positive evidence that fullsend, not the repo owner, installed the workflow block — the same ownership gate StripObsoleteGitLabWorkflowRules uses — so a user's own hand-written workflow: block is never modified.
Returns the original content and changed=false when there is nothing to merge (no workflow: block, the rule is already present, or fullsend ownership of the block can't be established).
func PollerCanCreatePipeline ¶ added in v0.44.0
func PollerCanCreatePipeline(rule *forge.ProtectedBranchRule, userIDs []int) bool
PollerCanCreatePipeline reports whether a Developer-level poller can create pipelines on the given protected ref. A nil rule means the branch is not protected and CreatePipeline does not need merge/push access. GitLab allows pipeline creation when the caller may merge or push; Developer (30) is included by any role-based grant at 30 or below (except 0, "No one"), or when a poller user ID is listed.
func PollerPipelineUserIDs ¶ added in v0.44.0
func PollerPipelineUserIDs(tokens []ProjectAccessToken) []int
PollerPipelineUserIDs returns the GitLab user IDs of active poller identities: the shared fullsend-bot token and the fullsend-poller role token. Analyst/coder tokens are omitted because they do not call CreatePipeline. Inactive, revoked, or zero-user-id tokens are skipped.
func RejectExtraneousURLParts ¶ added in v0.43.0
RejectExtraneousURLParts validates that a parsed URL contains only scheme and host — no path, userinfo, query, or fragment. The field parameter is used in error messages to identify the source.
func RemoveFromManifest ¶ added in v0.32.0
func RemoveFromManifest(cfg ManifestEditConfig, repos []string, progress ProgressFunc) (*ManifestRemoveResult, *Manifest, error)
RemoveFromManifest removes matching repo entries from all platform sections in the manifest. Patterns containing glob characters (*, ?, [) are matched against manifest entries using filepath.Match. Returns the result and the modified manifest.
func RuntimeSection ¶ added in v0.38.0
RuntimeSection renders the "Runtime" section appended to the scaffold PR body so the reviewer of a setup PR sees which agent runtime the repo will use and how to change it. An empty runtime means the default.
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 platform-level default in the manifest. An empty value removes the key. The file is created with version: 1 if it does not exist.
func StripObsoleteGitLabStages ¶ added in v0.44.0
StripObsoleteGitLabStages removes obsolete fullsend stages (see obsoleteGitLabStages) from an existing .gitlab-ci.yml, leaving everything else — including fullsend's current stages, user stages, includes, and workflow configuration — untouched. Unlike UnmergeGitLabCI (full teardown) this never removes fullsend's current stages; it only migrates away stages that are strictly obsolete.
An obsolete stage is only a stripping candidate when the file shows positive evidence that fullsend, not the repo owner, installed it: the fullsend pipeline include is present (this is an enrolled root CI file) AND at least one current fullsend stage is in the stages list (mergeStages ran and appended poll/agent alongside dispatch). A lone "dispatch" stage without poll or agent is treated as the repo's own and left in place. This gate differs from gitlabCIWorkflowIsFullsendOwned (workflow.name) because mergeStages never sets workflow.name — the merge-path repos that actually have stages: in the root file are exactly those that lack the name marker. Gating on the name would make this migration a no-op for the files that need it. "dispatch" is also not GitLab's standard MR-pipeline gate; the include-plus-current-stage fingerprint is the analogue of fullsend ownership for stages.
That fingerprint proves fullsend touched the stages: array, but not that a stage literally named "dispatch" is safe to delete — a repo enrolled via the merge path could independently have its own job on a "dispatch" stage, coexisting with fullsend's poll/agent. Deleting a stage that a job still references breaks the pipeline (GitLab rejects a job whose stage: isn't in stages:). So before removing an obsolete stage name, stageReferencedByJob scans top-level job definitions — including stages inherited via extends: or the YAML merge key (<<:) — for an effective stage: value matching it and, if found, leaves that stage in place — mirroring the conservative refusal gitlabCIWorkflowIsFullsendOwned already applies to the workflow: block. This scan only sees the root file's own top-level keys, so a second, non-fullsend include is also treated as absence of evidence: the root file might not be the whole picture, and a job living in that other include would be invisible to the scan.
Returns the original content and changed=false when there is nothing to strip (no stages: block, no obsolete stage present, fullsend ownership of the stages list can't be established, a non-fullsend include is also present, or every obsolete stage present is still referenced by a job).
func StripObsoleteGitLabWorkflowRules ¶ added in v0.44.0
StripObsoleteGitLabWorkflowRules removes obsolete fullsend workflow:rules entries (see obsoleteGitLabWorkflowRules) from an existing .gitlab-ci.yml, leaving everything else — including fullsend's current rules, the workflow name, auto_cancel settings, and any user configuration — untouched. Unlike UnmergeGitLabCI (full teardown) this never removes fullsend's current entries; it only migrates away rules that are strictly obsolete.
An obsolete rule is only stripped when gitlabCIWorkflowIsFullsendOwned finds positive evidence that fullsend, not the repo owner, installed the workflow block — the obsolete condition ($CI_PIPELINE_SOURCE == "merge_request_event") is GitLab's standard MR-pipeline gate and repos commonly set it themselves.
Returns the original content and changed=false when there is nothing to strip (no workflow: block, no rules:, no obsolete rule present, or fullsend ownership of the block can't be established).
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.
func UnmergeGitLabCI ¶ added in v0.38.0
UnmergeGitLabCI removes fullsend's CI configuration from a .gitlab-ci.yml. It removes the fullsend pipeline include entry and the fullsend workflow:rules entries. Returns the cleaned YAML, or nil if the file has no remaining meaningful content.
func UpdateAppSet ¶ added in v0.44.0
func UpdateAppSet(cfg ManifestEditConfig, filters []string, appSet string) ([]string, error)
UpdateAppSet applies a GitHub app-set override to manifest entries selected by filters. A concrete filter matching a glob entry gets an explicit entry so the override is limited to that repository; glob filters update the matching glob entries. The manifest is written when it changed unless DryRun is set.
func ValidateAllowedRemoteResourcesFormat ¶ added in v0.44.0
ValidateAllowedRemoteResourcesFormat checks that every entry in an allowed_remote_resources allowlist (repos.yaml defaults, a per-repo shorthand, or the shorthand once baked into a managed configuration file) is a well-formed prefix: a valid HTTPS URL, ending with "/", with no double-encoded sequences. These are the same format rules harness.ValidateAllowedRemoteResources applies at `fullsend run`/`lock` time; that check runs too late to guard this write path, since MatchingAllowedPrefixInList does a plain strings.HasPrefix match and a prefix missing its trailing slash can therefore match sibling hosts/paths it should not. It does not check coverage against an org-level allowlist — that requires the harness, which is not loaded here. Exported so repos.yaml write paths outside this package (the CLI's --allowed-remote-resources flag, `repos set-default`) can reject a malformed prefix before it is ever persisted, matching the check Manifest.Validate applies on load/converge.
Types ¶
type ComponentAction ¶ added in v0.38.0
type ComponentAction struct {
Component string // e.g., "workflow", "thin-caller:<path>", "var:MINT_URL", "schedule:<name>", "ref"
Action string // "none", "add", "update", "upgrade", "delete", "orphan", "error", ActionAdoptionRequired, ActionSafetyRejected
Detail string // human-readable detail
}
ComponentAction describes an action taken (or planned) on a single installation component during convergence.
type ComponentStatus ¶ added in v0.37.0
type ComponentStatus struct {
// Name identifies the component, prefixed by category:
// "workflow", "thin-caller:<path>", "scaffold:<path>", "var:<name>",
// "secret:<name>", "schedule:<name>"
Name string
// Present is true when the component exists on the forge.
Present bool
// Expected is the manifest's desired value. Empty when value
// checking does not apply (e.g., secrets whose values cannot be
// read back, or when no expected value was provided).
Expected string
// Actual is the component's current value on the forge. Empty
// when the component is not present or its value is opaque.
Actual string
// Match is true when the component meets its requirement. Both GCP
// secrets absent is also a match because Vertex is optional at install.
Match bool
}
ComponentStatus describes the state of a single installation component as probed from the forge. Both install and status use this to answer "what's wrong with this repo?" — install acts on the answer, status reports it.
func ProbeComponents ¶ added in v0.37.0
func ProbeComponents(ctx context.Context, client forge.Client, owner, repo, forgeName string, fc ForgeConfig, expectedVarValues map[string]string) ([]ComponentStatus, error)
ProbeComponents checks all per-repo installation components and returns their status.
Components checked:
- Shim workflow file (presence)
- GitLab trust script (presence)
- Per-repo thin callers (presence, GitHub only)
- Required variables (presence; values compared when expectedVarValues contains a non-empty entry for the variable name)
- Required secrets (presence only — values cannot be read back)
expectedVarValues maps variable names to their expected values for value-level drift detection. Pass nil for presence-only checking.
type ConfigBase ¶ added in v0.44.0
type ConfigBase struct {
Source string `yaml:"source,omitempty"`
SHA256 string `yaml:"sha256,omitempty"`
// contains filtered or unexported fields
}
ConfigBase is the nested config_base object in repos.yaml. Source is a local path or HTTPS URL written as .fullsend/config.base.yaml; SHA256 is an optional digest matching github setup --config-hash. Empty Source inherits the parent value; "none" disables inheritance. Empty SHA256 inherits the parent digest; "none" skips validation.
type ContentDriftFile ¶ added in v0.38.0
type ContentDriftFile struct {
// Path is the expected path from the template. Use InstalledPath
// when reporting drift to show the actual location on the forge.
Path string
// InstalledPath is the actual path of the file on the forge. For
// workflow files this may differ from Path due to extension
// differences (.yml vs .yaml).
InstalledPath string
// Expected is the rendered template content for this file.
Expected []byte
}
ContentDriftFile describes a scaffold file whose installed content differs from the expected template output after ref normalization.
func CheckFileContentDrift ¶ added in v0.38.0
func CheckFileContentDrift(ctx context.Context, client forge.Client, owner, repo string, fc ForgeConfig, forgeName string, expectedFiles []forge.TreeFile) ([]ContentDriftFile, error)
CheckFileContentDrift compares expected scaffold files against installed files on the forge, returning files whose content has drifted. Refs are normalized with replaceShimRef before comparison so that ref-format differences (tag vs SHA, annotation presence) do not produce false positives — ref drift is detected separately.
Both the status and converge paths use this function so they share the same comparison logic and cannot diverge.
Missing workflow and thin-caller files are handled by ProbeComponents; auxiliary scaffold files with forge-specific health semantics are also checked there.
type ConvergeBatchResult ¶ added in v0.38.0
type ConvergeBatchResult struct {
Results []ConvergeResult
}
ConvergeBatchResult holds the aggregate outcome of a batch convergence.
func Converge ¶ added in v0.38.0
func Converge(ctx context.Context, cfg ConvergeConfig, clients ForgeClientFactory, commitScaffold ScaffoldCommitFunc, progress ProgressFunc) (*ConvergeBatchResult, error)
Converge processes every repo in the manifest through a single convergence pipeline: probe → diff → apply. For each repo it determines what components exist and what actions are needed, then applies only the necessary changes.
This replaces the former two-phase architecture where BatchInstall handled new repos and a separate Upgrade + Sync pass handled already-installed repos.
func (*ConvergeBatchResult) AlreadyCurrent ¶ added in v0.38.0
func (r *ConvergeBatchResult) AlreadyCurrent() []ConvergeResult
AlreadyCurrent returns results where no action was needed.
func (*ConvergeBatchResult) Converged ¶ added in v0.38.0
func (r *ConvergeBatchResult) Converged() []ConvergeResult
Converged returns results where repos had drifted components repaired.
func (*ConvergeBatchResult) Failed ¶ added in v0.38.0
func (r *ConvergeBatchResult) Failed() []ConvergeResult
Failed returns results that errored.
func (*ConvergeBatchResult) Installed ¶ added in v0.38.0
func (r *ConvergeBatchResult) Installed() []ConvergeResult
Installed returns results where repos were newly installed.
type ConvergeConfig ¶ added in v0.38.0
type ConvergeConfig struct {
Manifest *Manifest
DryRun bool
RepoFilter []string
MaxConcurrency int
// Roles is the list of agent roles to install (e.g., "triage", "coder").
Roles []string
// RolesExplicit is true when the caller explicitly passed --roles,
// as opposed to Roles carrying the flag's own default value. Fresh
// installs of a repo with a declared configuration preset use this
// to decide whether to write roles into the overlay (explicit
// override) or leave them unset so the preset's roles (or the
// code-default fallback) take effect through the layered accessor
// chain — see BuildScaffoldFiles.
RolesExplicit bool
// 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
// Force allows downgrades when upgrading refs.
Force bool
// ReactivateSchedules opts in to reactivating a required GitLab
// pipeline schedule (fullsend slash poll / fullsend event poll) that
// exists but is disabled. Defaults to false: operators running
// off-system polling (see "Off-system polling" in
// configuring-gitlab.md) intentionally disable these schedules, so a
// disabled-but-present schedule is reported as drift but left alone
// unless this is set.
ReactivateSchedules bool
// InferenceProject is the GCP project ID for inference.
InferenceProject string
// InferenceProjectNumber is the numeric GCP project number,
// auto-derived from InferenceProject when WIFProvider is not set.
InferenceProjectNumber string
// InferenceRegion is the GCP region for inference.
InferenceRegion string
// WIFProvider, when set, is used as the WIF provider resource name
// for all repos instead of constructing per-repo provider IDs via
// BuildRepoProviderID. This supports org-scoped WIF providers
// (e.g., assertion.repository_owner == 'acme').
WIFProvider string
// ReviewAppClientID is the OAuth client ID of the review agent's
// GitHub App, pre-resolved by the caller for ReviewAppClientIDAppSet.
// It seeds the per-repo resolution cache so repos on that app set
// reuse it without a second lookup.
ReviewAppClientID string
// ReviewAppClientIDAppSet is the app set that ReviewAppClientID was
// resolved for. Repos whose effective app set differs (via a per-repo
// or platform app_set override) get their review client ID resolved
// independently so FULLSEND_REVIEW_CLIENT_ID tracks the same app set
// persisted as FULLSEND_APP_SET. Empty means ReviewAppClientID was
// resolved for the built-in default app set.
ReviewAppClientIDAppSet string
// VendorOverride, when non-nil, overrides the manifest's resolved
// vendor setting for all repos in this convergence run. This lets
// `repos install --vendor` take effect without modifying the
// manifest. When nil, the per-repo resolved Vendor field is used.
VendorOverride *bool
}
ConvergeConfig holds all inputs for a convergence operation that processes every repo through a single pipeline: probe → diff → apply. It replaces the former two-phase architecture where BatchInstall handled new repos and Upgrade + Sync handled already-installed repos.
type ConvergeResult ¶ added in v0.38.0
type ConvergeResult struct {
Owner string
Repo string
Actions []ComponentAction
// Installed is true when the repo was not previously installed and
// received a full install.
Installed bool
// NeedsGitLabPostInstall is true when GitLab pipeline schedules did
// not already exist on the repo before this run. GitLab post-install
// schedule setup is destructive — it deletes and recreates pipeline
// schedules — so it must run only when those artifacts are genuinely
// missing. Re-running install while the initialization MR is still
// open (#7417) keeps Installed true (workflow file still absent) but
// must not re-trigger this destructive setup once the schedules
// already exist from a prior run. This is deliberately narrower than
// "any fullsend-managed component exists" — the GCP inference secrets
// every Install() writes are unrelated to GitLab post-install and
// must not mask it having failed or never run. Shared-token bot-PAT
// setup is gone: role credentials are the only GitLab runtime path.
NeedsGitLabPostInstall bool
// NeedsGitLabPipelineSchedules is true when at least one pipeline
// schedule component (see PipelineScheduleSpecs) was not already
// present before this run. Callers must gate pipeline-schedule setup
// on this field, so a retry where the schedules already exist does
// not delete and recreate them.
NeedsGitLabPipelineSchedules bool
// Converged is true when the repo had drifted components that were
// repaired (variables, refs, or missing scaffold files).
Converged bool
// AlreadyCurrent is true when all components matched and no action
// was needed.
AlreadyCurrent bool
Error error
// WIFProvider is the WIF provider resource name used during install.
WIFProvider string
}
ConvergeResult holds the outcome of converging a single repo.
type DefaultsConfig ¶
type DefaultsConfig struct {
AllowedRemoteResources []string `yaml:"allowed_remote_resources,omitempty"`
// Runtime is the default agent runtime for every repo (claude, pi, codex).
Runtime string `yaml:"runtime,omitempty"`
// Vendor, when true, vendors the fullsend binary and content into
// each repo so CI does not need network access to fetch them.
Vendor *bool `yaml:"vendor,omitempty"`
// ConfigBase is the default configuration preset, written as
// .fullsend/config.base.yaml. Empty Source disables the default;
// source "none" disables inheritance for entries that reference it.
// SHA256 is an optional digest verified against the fetched preset.
ConfigBase ConfigBase `yaml:"config_base,omitempty"`
// Config is a fleet-wide sparse managed .fullsend/config.yaml
// (ADR 0122). Presence opts every repository into managed configuration.
Config config.ManagedConfig `yaml:"config,omitempty"`
}
DefaultsConfig holds default field values applied to every repo across all platforms.
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 DriftConfig ¶ added in v0.38.0
type DriftConfig struct {
// InferenceRegion is the GCP region for inference. Only available
// from CLI flags on repos install; empty on the status path.
InferenceRegion string
// ReviewAppClientID is the OAuth client ID of the review agent's
// GitHub App. Only available from CLI flags on repos install.
ReviewAppClientID string
// AgentRunnerTags is a list of GitLab CI runner tags from the
// manifest's GitLab platform section for agent (data-plane) jobs.
AgentRunnerTags []string
// ControlRunnerTags is a list of GitLab CI runner tags from the
// manifest's GitLab platform section for control-plane jobs. Already
// resolved through gitlabControlRunnerTags; independent of
// AgentRunnerTags, so an unset control_runner_tags stays empty here.
ControlRunnerTags []string
}
DriftConfig holds additional fields beyond ResolvedConfig that are needed to build a complete InstallConfig for drift detection. These fields come from the manifest or CLI flags and are not part of the per-repo resolved config.
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. The pipeline wrapper carries the version marker (#7707). Native dispatch itself was removed in #7322 (see ADR 0067). ShimRefPattern matches the injected ref: marker line for upgrade drift detection. Leftover fullsend-dispatch.yml from installs before #7707 is still read for the installed ref by readWorkflowMarker.
type GitLabPipelineAccessResult ¶ added in v0.44.0
GitLabPipelineAccessResult describes what EnsureGitLabPollerPipelineAccess did or would do for a repo's protected default branch.
func EnsureGitLabPollerPipelineAccess ¶ added in v0.44.0
func EnsureGitLabPollerPipelineAccess(ctx context.Context, client forge.Client, owner, repo string, userIDs []int, dryRun bool) (GitLabPipelineAccessResult, error)
EnsureGitLabPollerPipelineAccess makes a Developer-level poller able to CreatePipeline on the repo's default branch. When the branch is unprotected, or Developers already have merge or push, this is a no-op. Otherwise it grants each poller user merge access (not push) on that protected ref. GitHub clients that return ErrNotSupported are skipped.
type GitLabPipelineVarRestrictionResult ¶ added in v0.44.0
type GitLabPipelineVarRestrictionResult struct {
// Role is the value observed before any change ("" if GitLab never
// returned one, e.g. an older instance/edition).
Role string
// Action is one of "none", "report-only", "update", "would-update",
// or "unsupported". "none" means the project is already owner.
// "report-only" means the project is not owner but active
// enforcement is disabled, so no write was attempted.
Action string
Detail string
}
GitLabPipelineVarRestrictionResult describes what EnsureGitLabPipelineVariableOverrideRole did or would do for a repo.
func EnsureGitLabPipelineVariableOverrideRole ¶ added in v0.44.0
func EnsureGitLabPipelineVariableOverrideRole(ctx context.Context, client forge.Client, owner, repo string, dryRun bool) (GitLabPipelineVarRestrictionResult, error)
EnsureGitLabPipelineVariableOverrideRole reads a GitLab project's ci_pipeline_variables_minimum_override_role and, when enforcement is enabled (GitLabPipelineVarRestrictionEnforced), converges it to forge.PipelineVarOverrideOwner. It is idempotent: a project already set to owner is left untouched and reported as Action "none", so calling this repeatedly (fresh install, converge/repair, or an already-correct repo) never issues a redundant write. A project that is not owner while enforcement is disabled is reported as Action "report-only" (not "none"), so callers can distinguish "control already applied" from "control not yet applied" instead of rendering both as the same success status. GitHub repos, and any forge client that returns forge.ErrNotSupported, report Action "unsupported" and are never an error.
Enforcement defaults to off (report-only) because setting this to owner also blocks the Developer-level poller/dispatcher's own CreatePipeline(variables) call (internal/poll/dispatch.go) until the poller identity is raised to Owner — a credential-cost decision ADR 0125 and #7769 track as still open, and internal/repos/gitlab_roles.go / internal/repos/gitlab_pipeline_access.go are built assuming a Developer-level poller throughout. Do not flip GitLabPipelineVarRestrictionEnv to "enforced" fleet-wide until that follow-up ships; doing so before then breaks the poller's own dispatch pipeline on every enrolled repo.
type GitLabRoleCleanupConfig ¶ added in v0.44.0
type GitLabRoleCleanupConfig struct {
Owner string
Repo string
Client forge.Client
// Tokens, when set, revokes active role project access tokens. Nil
// skips PAT revocation; CI/CD variables and secrets are still
// deleted.
Tokens ProjectAccessTokenClient
DryRun bool
}
GitLabRoleCleanupConfig controls removal of GitLab role-identity installation state: the registry, rotation document, built-in and custom role secrets, and matching role project access tokens. It does not touch the legacy FULLSEND_FORGE_TOKEN shared secret or its fullsend-bot project access token — a repository installed before the role-only rollout may require manual cleanup of those.
type GitLabRoleCleanupResult ¶ added in v0.44.0
type GitLabRoleCleanupResult struct {
VarsDeleted int
TokensRevoked int
DryRun bool
Diagnostics []string
}
GitLabRoleCleanupResult is the non-secret outcome of identity cleanup.
func CleanupGitLabRoleIdentity ¶ added in v0.44.0
func CleanupGitLabRoleIdentity(ctx context.Context, cfg GitLabRoleCleanupConfig) (GitLabRoleCleanupResult, error)
CleanupGitLabRoleIdentity removes GitLab role-identity installation state without recreating any of it. Missing variables, secrets, or tokens are not errors, so retries and uninstall of partial installs stay idempotent. A token-inventory failure after variables are deleted is still returned so uninstall can fail closed and leave the manifest entry for retry.
This function never reads or returns secret values.
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 mint
// setup before calling Install).
SkipAppSetup 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
// Runtime, when set, is written as the per-repo `runtime:` of the
// generated config (`fullsend admin install <owner>/<repo> --runtime`).
// Empty keeps the code default; ignored when PerRepoConfig is set.
Runtime string
// VendorBinary renders scaffold workflows to reference the vendored
// binary path instead of fetching from upstream on each CI run.
VendorBinary bool
// ReviewAppClientID is the OAuth client ID of the review agent's
// GitHub App. When set, it is written as the FULLSEND_REVIEW_CLIENT_ID
// repo variable so that pre-fetch-prior-review.sh can validate
// provenance of prior review comments.
ReviewAppClientID string
// AppSet is the GitHub App set prefix (apps named "{app_set}-{role}").
// When set, it is written as the FULLSEND_APP_SET repo variable so the
// scaffold workflows can derive bot identities. GitHub-only; empty for
// GitLab, where no FULLSEND_APP_SET variable is written.
AppSet string
// AgentRunnerTags is a list of GitLab CI runner tags embedded in the
// agent job so sandbox work is routed to the data-plane fleet.
AgentRunnerTags []string
// ControlRunnerTags is a list of GitLab CI runner tags embedded in
// control-plane jobs (poll today). Independent of AgentRunnerTags:
// unset renders an empty (untagged) tag list, not the agent tags.
ControlRunnerTags []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
// ExistingSecrets lists the repo secret names (e.g.
// FULLSEND_GCP_PROJECT_ID) already confirmed present on the repo
// before this install runs. Install skips writing any secret named
// here individually, so an already-present secret is left untouched
// even when ReuseSecrets is false because only some of the required
// secrets exist yet (a partial-secret, workflow-missing re-install —
// see convergeRepo). ReuseSecrets remains the all-or-nothing signal
// used for the WIF-provider validation and progress messaging when
// every required secret already exists.
ExistingSecrets []string
// PrebuiltScaffoldFiles, when non-nil, replaces the embedded scaffold
// template collection. Used when fullsend_ref pins to a version that
// differs from the running binary, so templates are fetched from the
// fullsend-ai/fullsend repo at the pinned ref.
PrebuiltScaffoldFiles scaffold.InstallFiles
// Preset, when non-nil, is written byte-for-byte as
// .fullsend/config.base.yaml. The overlay is generated independently
// unless ManagedConfig is set.
Preset []byte
// ManagedConfig, when non-nil, is written as .fullsend/config.yaml
// instead of generating an installer overlay. Used for config-managed
// repositories (ADR 0122). Unmanaged repos leave this nil so existing
// installer generation is preserved.
ManagedConfig []byte
// ManagedConfigAdoptionRequired, when true, skips writing
// .fullsend/config.yaml entirely, even though ManagedConfig may be
// set: the caller found an existing file that does not carry the
// ADR-0122 ownership marker, or the pre-write safety gate rejected
// the candidate, so the file must be left untouched — the same
// contract convergeManagedConfigFiles enforces on the already-
// installed path. Callers that do not check for adoption or the
// safety gate (repos outside the managed-configuration install/
// converge flow) leave this false so existing behavior is unchanged.
ManagedConfigAdoptionRequired 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
// 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 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 ManagedVar ¶ added in v0.38.0
type ManagedVar struct {
Name string
Value string
Dynamic bool // true = presence-only (value mutated at runtime)
}
ManagedVar describes a repository variable with its expected value and whether it is dynamic (mutated at runtime). Static variables are value-checked during drift detection; dynamic variables are presence-checked only.
type Manifest ¶
type Manifest struct {
Version int `yaml:"version"`
Defaults DefaultsConfig `yaml:"defaults,omitempty"`
GitHub *PlatformConfig `yaml:"github,omitempty"`
GitLab *PlatformConfig `yaml:"gitlab,omitempty"`
// contains filtered or unexported fields
}
Manifest is the top-level structure of a repos.yaml file. Platform sections (github, gitlab) replace the former nested forge section. Each platform section contains infrastructure config AND its repos list.
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) AllRepos ¶ added in v0.37.0
AllRepos returns a flat list of all repo entries across all platform sections. The order is GitHub repos first, then GitLab repos, preserving the order within each section.
func (*Manifest) DistinctForges ¶ added in v0.33.0
DistinctForges returns the deduplicated set of forge names actually used by entries in the manifest. Only forges with a non-nil platform section containing repos are included. The order is deterministic (github before gitlab).
func (*Manifest) DistinctForgesFor ¶ added in v0.44.0
DistinctForgesFor returns the deduplicated set of forge names used by repos matching filter. An empty filter returns DistinctForges(). The order is deterministic (github before gitlab). A glob manifest entry counts as selected when a concrete filter would be produced by expanding it (for example entry "acme/*" and filter "acme/api"). An error is returned if a filter or manifest entry is an invalid glob pattern.
func (*Manifest) EnsurePlatform ¶ added in v0.37.0
func (m *Manifest) EnsurePlatform(forgeName string) *PlatformConfig
EnsurePlatform returns the PlatformConfig for the given forge name, creating it if it does not exist.
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) ExpandGlobsFor ¶ added in v0.44.0
func (m *Manifest) ExpandGlobsFor(ctx context.Context, clients ForgeClientFactory, filter []string) ([]ResolvedRepo, error)
ExpandGlobsFor is like ExpandGlobs, but skips expanding a platform's glob entries when filter is non-empty and does not select any repo on that platform. This keeps a filtered operation (e.g. "repos install gitlab-group/project") from requiring credentials for a forge that only appears via an unrelated glob entry (e.g. a GitHub "acme/*" entry) elsewhere in the manifest.
func (*Manifest) HasForge ¶ added in v0.33.0
HasForge reports whether any repo in the manifest resolves to the given forge name.
func (*Manifest) LayeredConfig ¶ added in v0.44.0
func (m *Manifest) LayeredConfig(entry RepoEntry, baseYAML []byte) (config.PerRepoConfigReader, error)
LayeredConfig returns the effective per-repo configuration for entry: managed configuration → config.base.yaml (baseYAML) → code defaults. Unmanaged repositories skip the managed layer. baseYAML may be empty.
func (*Manifest) Marshal ¶
Marshal serializes the manifest back to YAML. Deprecated runner_tags is dropped so rewrites emit agent_runner_tags. Marshal does not mutate the receiver: the deprecated-key migration runs against a shallow copy, so the caller's Manifest (and its platform configs) are unchanged after a call to Marshal.
func (*Manifest) PlatformFor ¶ added in v0.37.0
func (m *Manifest) PlatformFor(forgeName string) *PlatformConfig
PlatformFor returns the PlatformConfig for the given forge name, or nil if that platform section is not present in the manifest.
func (*Manifest) RenderManagedConfig ¶ added in v0.44.0
RenderManagedConfig returns the canonical sparse configuration YAML body for a config-managed repository — the explicitly supplied manifest values, with no code defaults or config.base.yaml baked in. ok is false when the repository is not config-managed; data is then nil.
The returned bytes deliberately carry no file header. perRepoConfig's Marshal() prepends perRepoConfigHeader, the unmanaged per-repo-install header — not the ADR 0122 ownership marker ("# This file is managed by 'fullsend repos': ...") that every managed .fullsend/config.yaml written by the install path begins with. This function has no adoption-detection state (no forge read of the existing file), so it cannot decide whether the marker belongs on the result or whether an existing file requires adoption first; it renders the config body only. desiredManagedConfig is the install-path renderer (#7632) that prefixes the marker and is compared against the installed file by convergeManagedConfigFiles / checkManagedConfigDrift in managed_config_lifecycle.go, which also implement the adoption gate for an existing markerless file.
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 platform sections. The resolution order is:
- Per-repo override (from RepoEntry)
- Platform-level default (from PlatformConfig)
- Built-in defaults (empty strings)
The sentinel value "none" 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 is empty.
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, forgeName string, entry RepoEntry) ResolvedConfig
ResolveConfigForEntry computes the fully merged configuration for the given owner/repo using the provided RepoEntry and forge name. 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) TotalRepoCount ¶ added in v0.37.0
TotalRepoCount returns the total number of repo entries across all platform sections.
func (*Manifest) Validate ¶
Validate checks the manifest for structural correctness:
- version must be 1
- github.url defaults to https://github.com when unset; mint_url defaults to DefaultPublicMintURL in public mode, and is required in private mode
- gitlab.url is required when a gitlab section is present with repos
- platform-specific fields are rejected on the wrong platform
- 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
// ReviewAppClientID is the OAuth client ID of the review agent's
// GitHub App. When set, it is written as FULLSEND_REVIEW_CLIENT_ID
// on each migrated repo.
ReviewAppClientID 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, 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)
- Removes the repository entry 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 OrphanFile ¶ added in v0.38.0
type OrphanFile struct {
Path string
}
OrphanFile describes a file that exists on the forge at a managed scaffold path but is no longer produced by the current template.
func CheckOrphanFiles ¶ added in v0.38.0
func CheckOrphanFiles(ctx context.Context, client forge.Client, owner, repo string, fc ForgeConfig, forgeName string, expectedFiles []forge.TreeFile) ([]OrphanFile, error)
CheckOrphanFiles compares the set of managed scaffold paths against the expected template output, checking which managed paths exist on the forge but are absent from the expected files. These are orphan files — leftover from a previous template version.
type OrphanVar ¶ added in v0.38.0
type OrphanVar struct {
Name string
}
OrphanVar describes a repository variable with the FULLSEND_ prefix that exists on the forge but is not in the current managed variable set.
func CheckOrphanVars ¶ added in v0.38.0
func CheckOrphanVars(ctx context.Context, client forge.Client, owner, repo string, cfg InstallConfig, mintURL string) ([]OrphanVar, error)
CheckOrphanVars lists all repository variables on the forge and returns those with the FULLSEND_ prefix that are not in the managed variable set for the given forge. These are orphan variables — leftover from a previous installation or a removed feature. GitLab retired poll-state variables (gitlabRetiredLegacyVars) are known-retired: they are not reported as orphans so already-installed repos do not warn during the migrate-then-delete transition.
The managed set is computed using the FULL superset of possible managed variables — conditional fields (InferenceRegion, ReviewAppClientID) are populated with placeholders so that variables like FULLSEND_GCP_REGION are never flagged as orphans just because the caller doesn't know their expected value.
type PlatformConfig ¶ added in v0.37.0
type PlatformConfig struct {
URL string `yaml:"url,omitempty"`
MintURL string `yaml:"mint_url,omitempty"`
MintMode string `yaml:"mint_mode,omitempty"`
FullsendRef string `yaml:"fullsend_ref,omitempty"`
// AppSet is the GitHub App set prefix (apps named "{app_set}-{role}")
// persisted as the FULLSEND_APP_SET repo variable. GitHub-only; the
// sentinel "none" resets a per-repo override back to the built-in
// default. Rejected under the gitlab platform.
AppSet string `yaml:"app_set,omitempty"`
// AgentRunnerTags routes GitLab agent (data-plane) jobs. GitLab-only.
AgentRunnerTags []string `yaml:"agent_runner_tags,omitempty"`
// ControlRunnerTags routes GitLab control-plane jobs (poll today;
// webhook dispatcher next). GitLab-only. Fully independent of
// AgentRunnerTags: there is no cross-fallback. Unset renders an
// empty tag list (untagged), not the agent tags.
ControlRunnerTags []string `yaml:"control_runner_tags,omitempty"`
// DeprecatedRunnerTags is the deprecated gitlab.runner_tags alias.
// Parse populates AgentRunnerTags from it when agent_runner_tags is
// unset; MarshalWithHeader / Manifest.Marshal drop it so rewrites
// emit agent_runner_tags.
DeprecatedRunnerTags []string `yaml:"runner_tags,omitempty"`
Repos []RepoEntry `yaml:"repos"`
}
PlatformConfig holds per-platform infrastructure settings and the list of repos managed under that platform. A single struct serves both GitHub and GitLab; validation rejects platform-specific fields on the wrong platform (e.g. mint_url under gitlab).
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., "scaffold", "vars", "secrets")
- message: a human-readable status message
type ProjectAccessToken ¶ added in v0.44.0
type ProjectAccessToken struct {
ID int
Name string
Token string
Active bool
ExpiresAt string
Revoked bool
UserID int
}
ProjectAccessToken is the subset of a GitLab project access token needed to store a role credential. Token is the secret value and is present only at creation time; it must never appear in logs, status, or Error strings.
type ProjectAccessTokenClient ¶ added in v0.44.0
type ProjectAccessTokenClient interface {
CreateProjectAccessToken(ctx context.Context, owner, repo, name string, scopes []string, accessLevel int, expiresAt string) (*ProjectAccessToken, error)
ListProjectAccessTokens(ctx context.Context, owner, repo string) ([]ProjectAccessToken, error)
RevokeProjectAccessToken(ctx context.Context, owner, repo string, tokenID int) error
}
ProjectAccessTokenClient creates, lists, and revokes GitLab project access tokens. Implementations must not log token values. List results typically omit Token (GitLab returns the secret only at creation).
type RefResolver ¶ added in v0.37.0
type RefResolver struct {
// contains filtered or unexported fields
}
RefResolver resolves symbolic fullsend_ref values (tags, branches) to commit SHAs on the fullsend-ai/fullsend repository. Results are cached so repeated calls for the same ref avoid redundant API calls.
func NewRefResolver ¶ added in v0.37.0
func NewRefResolver(client forge.Client) *RefResolver
NewRefResolver creates a resolver that uses the given GitHub client. The client must target GitHub's API since fullsend-ai/fullsend is always a GitHub repository.
func (*RefResolver) IsAncestor ¶ added in v0.37.0
func (r *RefResolver) IsAncestor(ctx context.Context, potentialAncestor, descendant string) (bool, error)
IsAncestor reports whether potentialAncestor is an ancestor of (or identical to) descendant in the fullsend-ai/fullsend repository. Both arguments must be commit SHAs. Returns false with a nil error when the relationship cannot be determined (e.g., diverged commits).
func (*RefResolver) Resolve ¶ added in v0.37.0
func (r *RefResolver) Resolve(ctx context.Context, ref string) string
Resolve resolves ref to a commit SHA on fullsend-ai/fullsend. If ref is already a SHA it is returned unchanged. Tags are tried first, then branches. If resolution fails, ref is returned as-is (graceful degradation to string comparison).
type RepoEntry ¶
type RepoEntry struct {
Name string `yaml:"name"`
FullsendRef string `yaml:"fullsend_ref,omitempty"`
MintURL string `yaml:"mint_url,omitempty"`
MintMode string `yaml:"mint_mode,omitempty"`
AllowedRemoteResources []string `yaml:"allowed_remote_resources,omitempty"`
// AppSet overrides the GitHub App set prefix for this repository,
// persisted as the FULLSEND_APP_SET repo variable. GitHub-only; the
// sentinel "none" resets back to the built-in default.
AppSet string `yaml:"app_set,omitempty"`
// Runtime is the agent runtime written as the repo's `runtime:` at
// install time (claude, pi, codex); empty inherits defaults.runtime,
// and an empty resolved value keeps the code default (claude).
Runtime string `yaml:"runtime,omitempty"`
// Vendor overrides the default vendor setting for this repo.
// nil inherits defaults.vendor; non-nil overrides it.
Vendor *bool `yaml:"vendor,omitempty"`
// ConfigBase configures the configuration preset written as
// .fullsend/config.base.yaml. Empty Source inherits
// defaults.config_base; source "none" disables inheritance. SHA256
// is an optional digest verified against the fetched preset.
ConfigBase ConfigBase `yaml:"config_base,omitempty"`
// Config is a sparse managed .fullsend/config.yaml for this
// repository (ADR 0122). Presence opts this repository into managed
// configuration even when the mapping is empty. runtime and
// allowed_remote_resources are rejected here; use the sibling fields.
Config config.ManagedConfig `yaml:"config,omitempty"`
}
RepoEntry represents a single repo or glob pattern in a platform's repos list. Always uses object form with name as the required field. Override fields use plain strings (config_base is a nested object); the sentinel value "none" stops the inheritance chain.
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, forgeName string, fc ForgeConfig) (RepoState, error)
ProbeRepoState reads a repo's current per-repo installation state by probing all installation components (workflow files, variables, secrets). A repo is considered per-repo installed when at least one required variable is present — a workflow file alone may come from per-org enrollment. Returns a zero RepoState when no required variables are found.
type RepoStatus ¶ added in v0.31.0
type RepoStatus struct {
Owner string `json:"owner"`
Repo string `json:"repo"`
Forge string `json:"forge,omitempty"`
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"`
// GitLab role-credential status. Names only; never token values.
GitLabRolesReady bool `json:"gitlab_roles_ready,omitempty"`
GitLabRolesPartial bool `json:"gitlab_roles_partial,omitempty"`
GitLabRoleDiagnostics []string `json:"gitlab_role_diagnostics,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
MintMode string
FullsendRef string
AllowedRemoteResources []string
// AppSet is the resolved GitHub App set prefix persisted as the
// FULLSEND_APP_SET repo variable. GitHub-only; empty for GitLab.
AppSet string
// AppSetExplicit reports whether app_set was explicitly configured
// (per-repo override or manifest default, including the "none"
// sentinel). When false, convergence preserves any existing
// FULLSEND_APP_SET value on the repo rather than forcing the default.
AppSetExplicit bool
// Runtime is the resolved agent runtime (entry, then defaults); empty
// means the code default.
Runtime string
// Vendor is true when the fullsend binary and content should be
// vendored into the repo for offline CI.
Vendor bool
// Config is the resolved preset source; empty means no preset is
// declared and an existing base file is preserved without comparison.
Config string
// ConfigHash is the resolved SHA-256 hex digest; empty skips
// digest validation.
ConfigHash string
// ConfigManaged reports whether this repository is opted into a
// managed .fullsend/config.yaml (ADR 0122). defaults.config opts every
// repository in; a repository config block opts in only that repository.
ConfigManaged bool
// Managed is the sparse managed configuration: defaults.config merged with
// the repository config, plus authoritative runtime and
// allowed_remote_resources shorthands. Nil when ConfigManaged is
// false. It does not bake in code defaults or config.base.yaml.
Managed config.PerRepoConfigWriter
}
ResolvedConfig is the fully resolved configuration for a single repository after merging manifest defaults and platform-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 RoleProvisionConfig ¶ added in v0.44.0
type RoleProvisionConfig struct {
Owner string
Repo string
Client forge.Client
Tokens ProjectAccessTokenClient
Registry gitlabroles.Registry
// RegistryProvided is true when the operator explicitly supplied
// --gitlab-role-registry this run, as opposed to Registry being
// populated from a previously stored registry variable. Used only
// to decide whether to surface a diagnostic when the supplied
// registry is not persisted.
RegistryProvided bool
// ProvidedTokens maps a role name to an administrator-supplied
// PAT (free-tier enrollment or a custom own credential). Values
// must never be logged.
ProvidedTokens map[gitlabroles.Role]string
Now time.Time
DryRun bool
}
RoleProvisionConfig is the input to ProvisionGitLabRoleCredentials.
type RoleProvisionFailure ¶ added in v0.44.0
type RoleProvisionFailure struct {
Role gitlabroles.Role
Secret string
Reason string
}
RoleProvisionFailure is a per-role error. Reason and Secret are names and messages only — never token values.
type RoleProvisionResult ¶ added in v0.44.0
type RoleProvisionResult struct {
Report gitlabroles.Report
Created []gitlabroles.Role
Enrolled []gitlabroles.Role
Skipped []gitlabroles.Role
Reused []gitlabroles.Role
Failed []RoleProvisionFailure
RegistryWritten bool
DryRun bool
Diagnostics []string
}
RoleProvisionResult is the observable outcome of a provision run. Token values are not included.
func ProvisionGitLabRoleCredentials ¶ added in v0.44.0
func ProvisionGitLabRoleCredentials(ctx context.Context, cfg RoleProvisionConfig) (RoleProvisionResult, error)
ProvisionGitLabRoleCredentials creates or enrolls credentials for every registered role (built-in and custom), stores them as protected masked CI/CD variables, writes the registry, and reports which roles are ready.
It never revokes or overwrites FULLSEND_FORGE_TOKEN. Existing role secrets are left in place (reinstall / retry). A failed role does not roll back roles that already succeeded. A repository installed before the role-only rollout may still carry FULLSEND_FORGE_TOKEN; provisioning does not retire it, and no automated path does — that leftover secret and its matching fullsend-bot project access token require manual cleanup.
type RoleRotateConfig ¶ added in v0.44.0
type RoleRotateConfig struct {
Owner string
Repo string
Client forge.Client
Tokens ProjectAccessTokenClient
Registry gitlabroles.Registry
// Roles limits rotation to these names. Empty means every
// own-credential registered role.
Roles []gitlabroles.Role
// Force rotates even when the current PAT is not yet due.
Force bool
// LeadTime is how far ahead of expiry a credential is due.
// Zero uses gitlabroles.DefaultRotationLead.
LeadTime time.Duration
// GracePeriod is how long the previous PAT stays active after a
// successful distribution so in-flight jobs can finish. Zero uses
// gitlabroles.DefaultRotationGrace.
GracePeriod time.Duration
Now time.Time
DryRun bool
Holder string
LockTTL time.Duration
// ProvidedTokens maps a role name to an administrator-supplied
// replacement PAT. Values must never be logged.
ProvidedTokens map[gitlabroles.Role]string
}
RoleRotateConfig is the input to RotateGitLabRoleCredentials.
type RoleRotateResult ¶ added in v0.44.0
type RoleRotateResult struct {
Report gitlabroles.Report
Rotated []gitlabroles.Role
Skipped []gitlabroles.Role
Reused []gitlabroles.Role
Failed []RoleProvisionFailure
Overlapping []gitlabroles.Role
RolledBack []gitlabroles.Role
Cleaned []gitlabroles.Role
InProgress []gitlabroles.Role
DryRun bool
Diagnostics []string
}
RoleRotateResult is the observable outcome of a rotation run. Token values are not included.
func RotateGitLabRoleCredentials ¶ added in v0.44.0
func RotateGitLabRoleCredentials(ctx context.Context, cfg RoleRotateConfig) (RoleRotateResult, error)
RotateGitLabRoleCredentials replaces due (or Force) own-credential GitLab role PATs without touching FULLSEND_FORGE_TOKEN.
Create-then-distribute is used instead of GitLab's rotate-in-place API so the previous credential stays valid until grace cleanup: in-flight jobs that already hold the old token keep working. A failed create or distribution rolls the attempt back (revokes only the unused replacement) and leaves the last known-good secret in place. Concurrent callers for the same role are serialized and idempotent within gitlabroles.IdempotentRotationWindow.
type ScaffoldCommitFunc ¶
type ScaffoldCommitFunc func(ctx context.Context, owner, repo string, files []forge.TreeFile, direct bool, installed bool) error
ScaffoldCommitFunc delivers scaffold files to a repository and returns any error encountered.
The installed parameter indicates whether the shim workflow is already on the default branch (true = upgrade, false = fresh install). CLI implementations use this to select the appropriate commit message, PR title, and branch. Fresh-install metadata (DefaultScaffoldBranch) must be used until that workflow lands, even if variables or secrets already exist from a previous incomplete run.
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 ScaffoldMetadataOpts ¶ added in v0.36.0
type ScaffoldMetadataOpts struct {
// GuardInstalled indicates whether the repo already has fullsend
// installed (true = upgrade path, false = fresh install). When nil,
// the function defaults to fresh-install metadata.
GuardInstalled *bool
// OldVersion, when non-empty, overrides the existing-version detection
// from the workflow file. Only meaningful on the upgrade path.
OldVersion string
}
ScaffoldMetadataOpts holds pre-fetched values for BuildScaffoldPRMetadata.
type ScaffoldPRMetadata ¶ added in v0.36.0
ScaffoldPRMetadata holds commit/PR metadata for scaffold file delivery. Values differ based on whether this is a fresh install or a version upgrade.
func BuildScaffoldPRMetadata ¶ added in v0.36.0
func BuildScaffoldPRMetadata(ctx context.Context, client forge.Client, owner, repo, upstreamTag string, opts ...ScaffoldMetadataOpts) ScaffoldPRMetadata
BuildScaffoldPRMetadata returns PR metadata appropriate for the operation type: fresh install vs. version upgrade. Callers must indicate whether the repo is already installed via opts.GuardInstalled; when nil the function defaults to fresh-install metadata.
func UninstallPRMetadata ¶ added in v0.44.0
func UninstallPRMetadata() ScaffoldPRMetadata
UninstallPRMetadata returns commit/PR metadata for scaffold file removal.
Branch intentionally reuses DefaultScaffoldBranch rather than a distinct uninstall branch name: already-deployed per-repo shims (see internal/scaffold/fullsend-repo/templates/shim-per-repo.yaml and shim-workflow-call.yaml) only skip dispatch for head.ref == "fullsend/scaffold-install". A separate uninstall branch name would fail open and let the teardown PR trigger the fullsend dispatch job (with live WIF/mint credentials) against itself.
Known limitation: because install and uninstall share a branch, an in-flight PR from one operation is not closed or relabeled when the other operation runs against the same repo (closeStaleScaffoldPRs in internal/layers/commit.go skips the current branch, and commitBranchAndPR treats an "already exists" PR as success without updating its title or body). If `repos install`/`converge` and `repos uninstall` race on the same repo, the surviving PR's title and body can describe the opposite of what its diff now does (e.g., an "initialize fullsend" PR whose diff deletes the workflow files, or vice versa). This is accepted for now — see docs/cli/repos.md's `repos uninstall` section — rather than adding branch-content detection or a forge "update PR title/body" call.
type ScheduleSpec ¶ added in v0.39.0
type ScheduleSpec struct {
// ComponentName is the probe component name (e.g., "schedule:slash-poll").
ComponentName string
// Description is the human-readable schedule description stored in GitLab.
Description string
// Cron is the cron expression for the schedule.
Cron string
// Variables are the CI/CD variables set on the schedule trigger.
Variables map[string]string
}
ScheduleSpec defines a fullsend pipeline schedule for GitLab repos. All sites that create, detect, or match pipeline schedules must use PipelineScheduleSpecs() to stay in sync.
func PipelineScheduleSpecs ¶ added in v0.39.0
func PipelineScheduleSpecs() []ScheduleSpec
PipelineScheduleSpecs returns the canonical list of fullsend pipeline schedules for GitLab repos.
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. variables present but workflow read fails), so Installed + NotInstalled + Errored may exceed Total.
type UninstallConfig ¶ added in v0.32.0
type UninstallConfig struct {
Manifest *Manifest
Repos []string
DryRun bool
// Direct controls scaffold file removal: true pushes deletions
// directly to the default branch; false creates a PR. Variable
// and secret deletions are API-only and always happen immediately.
Direct bool
MaxConcurrency int
// GitLabTokens, when set, revokes GitLab role and shared-bot project
// access tokens during uninstall. Nil skips PAT revocation; CI/CD
// variables and secrets are still deleted. A revocation failure
// fails the uninstall so the manifest entry remains for retry.
GitLabTokens ProjectAccessTokenClient
}
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
TokensRevoked 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, commitScaffold ScaffoldCommitFunc, 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) removes scaffold files via commitScaffold (PR by default, or a direct push when cfg.Direct is true), then deletes variables and secrets via the forge API.
GCP WIF cleanup is handled separately via `inference deprovision`.
Does NOT modify repos.yaml — use RemoveFromManifest for that.
Source Files
¶
- config_preset.go
- converge.go
- discover.go
- drift.go
- forge_config.go
- gitlab_pipeline_access.go
- gitlab_pipeline_var_restriction.go
- gitlab_roles.go
- gitlab_roles_cleanup.go
- gitlab_roles_rotate.go
- gitlabci.go
- install.go
- managed_config.go
- managed_config_lifecycle.go
- manifest.go
- manifest_edit.go
- migrate.go
- probe.go
- ref_ops.go
- ref_resolve.go
- remote_scaffold.go
- scaffold_metadata.go
- schedules.go
- status.go
- uninstall.go