Documentation
¶
Index ¶
- type AgentCredentials
- type ConfigRepoLayer
- func (l *ConfigRepoLayer) Analyze(ctx context.Context) (*LayerReport, error)
- func (l *ConfigRepoLayer) Install(ctx context.Context) error
- func (l *ConfigRepoLayer) Name() string
- func (l *ConfigRepoLayer) RequiredScopes(op Operation) []string
- func (l *ConfigRepoLayer) Uninstall(ctx context.Context) error
- type DispatchTokenLayer
- func (l *DispatchTokenLayer) Analyze(ctx context.Context) (*LayerReport, error)
- func (l *DispatchTokenLayer) Install(ctx context.Context) error
- func (l *DispatchTokenLayer) Name() string
- func (l *DispatchTokenLayer) RequiredScopes(op Operation) []string
- func (l *DispatchTokenLayer) Uninstall(ctx context.Context) error
- type EnrollmentLayer
- func (l *EnrollmentLayer) Analyze(ctx context.Context) (*LayerReport, error)
- func (l *EnrollmentLayer) Install(ctx context.Context) error
- func (l *EnrollmentLayer) Name() string
- func (l *EnrollmentLayer) RequiredScopes(op Operation) []string
- func (l *EnrollmentLayer) Uninstall(_ context.Context) error
- type Layer
- type LayerReport
- type LayerStatus
- type Operation
- type PreflightResult
- type SecretsLayer
- type Stack
- func (s *Stack) AnalyzeAll(ctx context.Context) ([]*LayerReport, error)
- func (s *Stack) CollectRequiredScopes(op Operation) []string
- func (s *Stack) InstallAll(ctx context.Context) error
- func (s *Stack) Layers() []Layer
- func (s *Stack) Preflight(ctx context.Context, op Operation, client forge.Client) (*PreflightResult, error)
- func (s *Stack) UninstallAll(ctx context.Context) []error
- type WorkflowsLayer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentCredentials ¶
type AgentCredentials struct {
config.AgentEntry
PEM string
AppID int
}
AgentCredentials extends AgentEntry with app credentials.
type ConfigRepoLayer ¶
type ConfigRepoLayer struct {
// contains filtered or unexported fields
}
ConfigRepoLayer manages the .fullsend configuration repository. This is the foundational layer — it must be installed before any other layers that depend on the config repo existing.
func NewConfigRepoLayer ¶
func NewConfigRepoLayer(org string, client forge.Client, cfg *config.OrgConfig, printer *ui.Printer, hasPrivate bool) *ConfigRepoLayer
NewConfigRepoLayer creates a new ConfigRepoLayer. Set hasPrivate to true if the org has any private repos — the config repo will be created as private to match the org's existing pattern. For orgs with only public repos (e.g., open source orgs), it is created as public to avoid surprises. This matters because the .fullsend repo may contain workflow files referenced by public repos.
func (*ConfigRepoLayer) Analyze ¶
func (l *ConfigRepoLayer) Analyze(ctx context.Context) (*LayerReport, error)
Analyze checks whether the .fullsend repo and config.yaml exist and are valid.
func (*ConfigRepoLayer) Install ¶
func (l *ConfigRepoLayer) Install(ctx context.Context) error
Install creates the .fullsend config repo (if it doesn't exist) and writes config.yaml into it.
Timing note: after CreateRepo with auto_init, the default branch may not be fully materialized yet. The Contents API call to write config.yaml can get transient 404s. The GitHub client's retry-with-backoff in do() handles this, but callers should be aware that the first file write to a newly created repo may take several seconds to succeed.
func (*ConfigRepoLayer) Name ¶
func (l *ConfigRepoLayer) Name() string
func (*ConfigRepoLayer) RequiredScopes ¶
func (l *ConfigRepoLayer) RequiredScopes(op Operation) []string
RequiredScopes returns the scopes needed for the given operation.
type DispatchTokenLayer ¶
type DispatchTokenLayer struct {
// contains filtered or unexported fields
}
DispatchTokenLayer manages the org-level dispatch token that enrolled repos use to trigger workflow_dispatch events on the .fullsend repo.
The dispatch token is a fine-grained PAT scoped to the .fullsend repo with actions:write permission. It is stored as an org-level Actions secret with visibility "selected", scoped to enrolled repos only. This way, enrolled repos can trigger dispatches but never access the App private keys (which are repo-level secrets on .fullsend).
func NewDispatchTokenLayer ¶
func NewDispatchTokenLayer(org string, client forge.Client, token string, repoIDs []int64, printer *ui.Printer) *DispatchTokenLayer
NewDispatchTokenLayer creates a new DispatchTokenLayer.
func (*DispatchTokenLayer) Analyze ¶
func (l *DispatchTokenLayer) Analyze(ctx context.Context) (*LayerReport, error)
Analyze checks whether the dispatch token org secret exists.
func (*DispatchTokenLayer) Install ¶
func (l *DispatchTokenLayer) Install(ctx context.Context) error
Install creates or updates the org-level dispatch token secret. If dispatchToken is empty, the secret value is reused (not recreated), but the repo access list is still updated if enrolledRepoIDs is set.
func (*DispatchTokenLayer) Name ¶
func (l *DispatchTokenLayer) Name() string
Name returns the layer name.
func (*DispatchTokenLayer) RequiredScopes ¶
func (l *DispatchTokenLayer) RequiredScopes(op Operation) []string
RequiredScopes returns the scopes needed for the given operation.
type EnrollmentLayer ¶
type EnrollmentLayer struct {
// contains filtered or unexported fields
}
EnrollmentLayer manages repo enrollment in the fullsend pipeline. It creates PRs with shim workflow files that route events to the reusable agent dispatch workflow in the .fullsend config repo.
func NewEnrollmentLayer ¶
func NewEnrollmentLayer(org string, client forge.Client, enabledRepos []string, defaultBranches map[string]string, printer *ui.Printer) *EnrollmentLayer
NewEnrollmentLayer creates a new EnrollmentLayer.
func (*EnrollmentLayer) Analyze ¶
func (l *EnrollmentLayer) Analyze(ctx context.Context) (*LayerReport, error)
Analyze checks which enabled repos have the shim workflow installed.
func (*EnrollmentLayer) Install ¶
func (l *EnrollmentLayer) Install(ctx context.Context) error
Install creates enrollment PRs for enabled repos that are not yet enrolled. Failures on individual repos are warned and skipped — install does not stop.
func (*EnrollmentLayer) Name ¶
func (l *EnrollmentLayer) Name() string
func (*EnrollmentLayer) RequiredScopes ¶
func (l *EnrollmentLayer) RequiredScopes(op Operation) []string
RequiredScopes returns the scopes needed for the given operation.
type Layer ¶
type Layer interface {
// Name returns a human-readable name for this layer.
Name() string
// RequiredScopes returns the OAuth scopes this layer needs for the
// given operation. Scopes are GitHub-flavored strings like "repo",
// "delete_repo", "workflow". Used by Preflight to fail early when
// the token is missing required scopes.
RequiredScopes(op Operation) []string
// Install creates or configures this layer's concern.
Install(ctx context.Context) error
// Uninstall tears down this layer's concern.
Uninstall(ctx context.Context) error
// Analyze assesses the current state and reports what would change.
Analyze(ctx context.Context) (*LayerReport, error)
}
Layer is the interface each installation concern implements. Layers are processed in order for install, reverse order for uninstall.
type LayerReport ¶
type LayerReport struct {
Name string
Status LayerStatus
Details []string // human-readable detail lines
WouldInstall []string // what install would create
WouldFix []string // what install would fix (for degraded state)
}
LayerReport is the result of analyzing a single layer.
type LayerStatus ¶
type LayerStatus int
LayerStatus represents the current state of a layer.
const ( StatusNotInstalled LayerStatus = iota StatusInstalled StatusDegraded // partially installed or misconfigured StatusUnknown // cannot determine )
func (LayerStatus) String ¶
func (s LayerStatus) String() string
String returns a human-readable description of the status.
type Operation ¶
type Operation int
Operation identifies which action is being performed on a layer.
type PreflightResult ¶
type PreflightResult struct {
// Required is the set of scopes the operation needs.
Required []string
// Granted is the set of scopes the token actually has.
Granted []string
// Missing is the set of scopes needed but not granted.
Missing []string
// Skipped is true when scope introspection was unavailable
// (e.g., fine-grained tokens that don't report scopes).
Skipped bool
}
PreflightResult describes what a preflight check found.
func (*PreflightResult) Error ¶
func (r *PreflightResult) Error() string
Error returns a human-readable error describing missing scopes and how to fix the problem.
func (*PreflightResult) OK ¶
func (r *PreflightResult) OK() bool
OK returns true if no scopes are missing.
type SecretsLayer ¶
type SecretsLayer struct {
// contains filtered or unexported fields
}
SecretsLayer manages agent app secrets and variables in the .fullsend repo.
func NewSecretsLayer ¶
func NewSecretsLayer(org string, client forge.Client, agents []AgentCredentials, printer *ui.Printer) *SecretsLayer
NewSecretsLayer creates a new SecretsLayer.
func (*SecretsLayer) Analyze ¶
func (s *SecretsLayer) Analyze(ctx context.Context) (*LayerReport, error)
Analyze checks whether all expected agent secrets and variables exist in the .fullsend repo.
func (*SecretsLayer) Install ¶
func (s *SecretsLayer) Install(ctx context.Context) error
Install stores agent app private keys as repo secrets and app IDs as repo variables in the .fullsend config repo.
func (*SecretsLayer) RequiredScopes ¶
func (s *SecretsLayer) RequiredScopes(op Operation) []string
RequiredScopes returns the scopes needed for the given operation.
type Stack ¶
type Stack struct {
// contains filtered or unexported fields
}
Stack is an ordered collection of layers.
func (*Stack) AnalyzeAll ¶
func (s *Stack) AnalyzeAll(ctx context.Context) ([]*LayerReport, error)
AnalyzeAll runs Analyze on each layer and returns reports.
func (*Stack) CollectRequiredScopes ¶
CollectRequiredScopes returns the deduplicated set of scopes needed by all layers for the given operation.
func (*Stack) InstallAll ¶
InstallAll runs Install on each layer in order. Stops on first error, returning the error and the name of the failed layer.
func (*Stack) Preflight ¶
func (s *Stack) Preflight(ctx context.Context, op Operation, client forge.Client) (*PreflightResult, error)
Preflight checks that the forge client's token has all the scopes required by the stack's layers for the given operation. It returns a PreflightResult describing what was found.
If the forge doesn't support scope introspection (e.g., fine-grained tokens, GitHub App tokens), Preflight returns a result with OK() == true and logs that scope checking was skipped. We can't validate what we can't see, so we let the operation proceed and fail at the point of use if scopes are actually missing.
type WorkflowsLayer ¶
type WorkflowsLayer struct {
// contains filtered or unexported fields
}
WorkflowsLayer manages workflow files and CODEOWNERS in the .fullsend config repo. It writes the reusable agent dispatch workflow, the repo onboarding workflow, and a CODEOWNERS file that grants the installing user ownership of all config-repo contents.
func NewWorkflowsLayer ¶
func NewWorkflowsLayer(org string, client forge.Client, printer *ui.Printer, user string) *WorkflowsLayer
NewWorkflowsLayer creates a new WorkflowsLayer. user is the authenticated user who will own CODEOWNERS entries.
func (*WorkflowsLayer) Analyze ¶
func (l *WorkflowsLayer) Analyze(ctx context.Context) (*LayerReport, error)
Analyze checks which managed files exist in the config repo.
func (*WorkflowsLayer) Install ¶
func (l *WorkflowsLayer) Install(ctx context.Context) error
Install writes the workflow files and CODEOWNERS to the .fullsend repo. CODEOWNERS failure is treated as a warning, not a fatal error.
Note: writing multiple files sequentially via the Contents API can cause transient 404s because each file write creates a new commit and the branch ref is updated asynchronously. The GitHub client's retry logic handles this. CODEOWNERS is written last and its failure is non-fatal because some orgs restrict CODEOWNERS writes to specific teams.
func (*WorkflowsLayer) Name ¶
func (l *WorkflowsLayer) Name() string
func (*WorkflowsLayer) RequiredScopes ¶
func (l *WorkflowsLayer) RequiredScopes(op Operation) []string
RequiredScopes returns the scopes needed for the given operation.