postbuild

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 CollectNarratorBadgeItems(appCfg *config.Config) []config.NarratorItem
• func DockerHubFromConfig(appCfg *config.Config) (string, string)
• func EnsureHarborProjects(ctx context.Context, registries []build.RegistryTarget) error
• func FirstDockerReadmeDescription(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 ReadmeHook() pipeline.PostBuildHook
• func RetentionHook() pipeline.PostBuildHook
• func RunBadgeSection(w io.Writer, color bool, rootDir string, appCfg *config.Config) (string, time.Duration)
• func RunReadmeSection(ctx context.Context, w io.Writer, _ bool, color bool, ...) (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)
• type BadgeRunner
• type PushFailure
• type PushRecoveryResult
  • func RecoverPushFailure(ctx context.Context, registries []build.RegistryTarget, failure PushFailure) PushRecoveryResult

Functions

func BadgeHook

func BadgeHook(appCfg *config.Config, runner BadgeRunner) pipeline.PostBuildHook

BadgeHook generates configured badges. Condition: returns true only if narrator 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 CollectNarratorBadgeItems

func CollectNarratorBadgeItems(appCfg *config.Config) []config.NarratorItem

CollectNarratorBadgeItems returns all narrator items with badge generation configured.

func DockerHubFromConfig

func DockerHubFromConfig(appCfg *config.Config) (string, string)

DockerHubFromConfig returns the namespace and repo for the first docker.io registry target.

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 FirstDockerReadmeDescription

func FirstDockerReadmeDescription(cfg *config.Config) string

FirstDockerReadmeDescription returns the description from the first docker-readme target.

func HasRetention

func HasRetention(plan *build.BuildPlan) bool

HasRetention returns true if any step has a registry with retention configured.

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 ReadmeHook

func ReadmeHook() pipeline.PostBuildHook

ReadmeHook syncs README to docker-readme targets.

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 RunReadmeSection

func RunReadmeSection(ctx context.Context, w io.Writer, _ bool, color bool, targets []config.TargetConfig, rootDir string, appCfg *config.Config) (string, time.Duration)

RunReadmeSection syncs README to docker-readme targets with section-formatted output. Returns a summary string and elapsed time for the summary table.

func RunRetentionSection

func RunRetentionSection(ctx context.Context, w io.Writer, _ bool, color bool, plan *build.BuildPlan) (string, time.Duration)

RunRetentionSection applies tag retention with section-formatted output. Returns a summary string and elapsed time for the summary table.

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

Types

type BadgeRunner

type BadgeRunner func(w io.Writer, color bool, rootDir string) (string, time.Duration)

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?).