Documentation
¶
Overview ¶
Package postbuild contains post-build hook adapters that coordinate between the pipeline framework and external system packages (registry, badge, etc.). These are integration glue — they belong to neither the pure system packages nor the generic pipeline framework.
Package postbuild contains post-build hook adapters and pipeline↔registry coordination glue. Harbor functions sit here because they coordinate between build plan types and registry clients — same layer as the hooks.
Index ¶
- func BadgeHook(appCfg *config.Config, runner BadgeRunner) pipeline.PostBuildHook
- func ClassifyPushFailure(failure PushFailure) string
- func CollectScribeBadgeItems(appCfg *config.Config) []config.StencilDef
- func EnsureHarborProjects(ctx context.Context, registries []build.RegistryTarget) error
- func FirstProjectDescription(cfg *config.Config) string
- func HasRetention(plan *build.BuildPlan) bool
- func IsHarborProjectMissingPushError(registries []build.RegistryTarget, failure PushFailure) bool
- func PostPushHooks(ctx context.Context, registries []build.RegistryTarget)
- func RenderBadgeSVG(eng *badge.Engine, spec config.BadgeSpec, value, statusColorSource string) (svg, color string)
- func ResolveBadgeValues(ctx context.Context, specs []config.BadgeSpec, vi *gitver.VersionInfo, ...) []string
- func RetentionHook() pipeline.PostBuildHook
- func RunBadgeSection(w io.Writer, color bool, rootDir string, appCfg *config.Config) (string, time.Duration)
- func RunMetadataSection(ctx context.Context, w io.Writer, color bool, targets []config.TargetConfig, ...) (string, time.Duration)
- func RunRetentionSection(ctx context.Context, w io.Writer, _ bool, color bool, plan *build.BuildPlan) (string, time.Duration)
- func TriggerHarborScans(ctx context.Context, registries []build.RegistryTarget)
- func ValueUnresolved(spec config.BadgeSpec, value string) bool
- type BadgeRunner
- type PushFailure
- type PushRecoveryResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BadgeHook ¶
func BadgeHook(appCfg *config.Config, runner BadgeRunner) pipeline.PostBuildHook
BadgeHook generates configured badges. Condition: returns true only if scribe config has badge items. runner is required and non-nil by contract — every caller has a legitimate badge runner.
func ClassifyPushFailure ¶
func ClassifyPushFailure(failure PushFailure) string
ClassifyPushFailure returns a short operator-meaningful reason for a push failure, with an owner tag in parentheses. Classification uses keyword heuristics — push CLI exit codes don't differentiate error types.
func CollectScribeBadgeItems ¶ added in v0.8.0
func CollectScribeBadgeItems(appCfg *config.Config) []config.StencilDef
CollectScribeBadgeItems returns all scribe content defs that generate a badge SVG.
func EnsureHarborProjects ¶
func EnsureHarborProjects(ctx context.Context, registries []build.RegistryTarget) error
EnsureHarborProjects pre-creates Harbor projects for all Harbor registry targets that have credentials configured. Must be called after Login() and only when a real remote push will occur. Dedupes by (registryURL, project).
func FirstProjectDescription ¶ added in v0.8.0
FirstProjectDescription returns the project description from the first metadata target — for injecting into badges/build context.
func HasRetention ¶
HasRetention returns true if any LOCAL-daemon registry has retention configured.
Remote registry tag deletion is a mutation of an external distribution target, so it belongs to the publish phase (after the push, when the final remote tag set is known) — see pruneRemoteRegistries. Perform owns only local Docker daemon hygiene: deleting images from the build daemon is workspace cleanup, not distribution, and the daemon does not survive into the separate publish job.
func IsHarborProjectMissingPushError ¶
func IsHarborProjectMissingPushError(registries []build.RegistryTarget, failure PushFailure) bool
IsHarborProjectMissingPushError reports whether the given push stderr appears to indicate a Harbor "project not found" failure. Returns false immediately if no Harbor registries are present.
This is a narrow heuristic used only for recovery (auto-create + retry), not a definitive classification of Harbor errors.
func PostPushHooks ¶
func PostPushHooks(ctx context.Context, registries []build.RegistryTarget)
PostPushHooks runs vendor-specific post-push actions (e.g. scan triggers). Best-effort — failures are warned, never fatal.
func RenderBadgeSVG ¶ added in v0.10.0
func RenderBadgeSVG(eng *badge.Engine, spec config.BadgeSpec, value, statusColorSource string) (svg, color string)
RenderBadgeSVG applies the empty/unresolved-value guard, resolves the badge's color, and renders its SVG — the shared per-item generation both badge generators use (the CI post-build hook and the CLI). They differ only in the auto-color source: the CI hook colors from the resolved value (statusColorSource ""), the CLI from the pipeline status.
Guard: a value with a leftover "{" means a template didn't resolve → "n/a", UNLESS the spec used a {{…}} literal (then the "{" is intentional, e.g. a "dev-{sha}" scheme).
func ResolveBadgeValues ¶ added in v0.10.0
func ResolveBadgeValues(ctx context.Context, specs []config.BadgeSpec, vi *gitver.VersionInfo, rootDir string, cfg *config.Config) []string
ResolveBadgeValues resolves each badge spec's templated Value through the full fact pipeline, in dependency order — the single ordered resolution path shared by both badge generators (the CI post-build hook RunBadgeSection and the CLI RunConfigBadges used by `scribe apply` / narrate). New fact families join HERE, not in each caller. The passes, in order:
- gitver leaf pass, per value — version/vars/commit/project/date/… (a var value may itself carry a downstream token, which the leaf pass resolves recursively).
- {registry.<id>.*} — batch across all values, each registry fetched once.
- {inventory.<cluster>.count} — batch, each gitops cluster discovered once.
The batch passes are ordered after the leaf pass and are offline no-ops when no {registry.*}/{inventory.*} tokens are present.
func RetentionHook ¶
func RetentionHook() pipeline.PostBuildHook
RetentionHook applies tag retention to configured registries.
func RunBadgeSection ¶
func RunBadgeSection(w io.Writer, color bool, rootDir string, appCfg *config.Config) (string, time.Duration)
RunBadgeSection generates configured badges with section-formatted output.
func RunMetadataSection ¶ added in v0.8.0
func RunMetadataSection(ctx context.Context, w io.Writer, color bool, targets []config.TargetConfig, rootDir string, appCfg *config.Config) (string, time.Duration)
RunMetadataSection pushes each kind: metadata target's identity to its registry: and repos: destinations, routing each field to what the destination supports and reporting set/skipped/warned honestly. Never truncates, never touches org scope.
func RunRetentionSection ¶
func RunRetentionSection(ctx context.Context, w io.Writer, _ bool, color bool, plan *build.BuildPlan) (string, time.Duration)
RunRetentionSection applies LOCAL-daemon image retention with section-formatted output. Returns a summary string and elapsed time for the summary table. Remote registries are intentionally skipped here — their retention runs in the publish phase (pruneRemoteRegistries), the only phase permitted to mutate external distribution targets.
func TriggerHarborScans ¶
func TriggerHarborScans(ctx context.Context, registries []build.RegistryTarget)
TriggerHarborScans fires a vulnerability scan on Harbor for each pushed tag where native_scan: true is configured. Best-effort — scan failures are warned, never fail the build. Must be called after push. Dedupes by (registryURL, path, tag).
func ValueUnresolved ¶ added in v0.13.0
ValueUnresolved reports whether a resolved badge value is really a failure to resolve: empty, or still carrying a "{" from a template that found no fact. A {{…}} literal in the spec is exempt, because there the brace is the point (the "dev-{sha}" scheme names a tag rather than resolving one).
Exported so writers can distinguish "this badge says n/a" from "this badge could not be computed here" — the second is not a value worth persisting over one that was.
Types ¶
type BadgeRunner ¶
BadgeRunner generates badges and returns a summary + elapsed time.
type PushFailure ¶
type PushFailure struct {
Err error // the original error
ExitCode int // process exit code (1 if not determinable)
Stderr string // stderr from the failed operation
Tag string // specific ref that failed (empty for multi-platform)
}
PushFailure carries structured context about a failed push operation. Both multi-platform (BuildWithLayers) and single-platform (PushTags) paths produce this type for recovery classification.
type PushRecoveryResult ¶
type PushRecoveryResult struct {
Retry bool // true = recovery action succeeded, caller should retry
Message string // diagnostic message for the caller to log
}
PushRecoveryResult tells the caller whether a push failure was recoverable.
func RecoverPushFailure ¶
func RecoverPushFailure(ctx context.Context, registries []build.RegistryTarget, failure PushFailure) PushRecoveryResult
RecoverPushFailure inspects a push failure and attempts vendor-specific recovery (e.g. creating a missing Harbor project). Returns whether the caller should retry the failed operation.
execute.go owns retry mechanics (which tags, stderr reset). This function owns the vendor decision (is this recoverable? what action to take?).
Source Files