push

Documentation

Overview

Package push implements the push workflow for uploading packs to remote registries.

The push workflow uses the Remote Adapter Protocol to communicate with registry backends. Remote adapters are external binaries (epack-remote-<name>) that handle authentication and upload operations. See the internal/remote package for protocol details.

Workflow

The push workflow consists of:

1. Load and verify the pack locally
2. Load remote configuration from epack.yaml
3. Discover and validate the adapter binary
4. Call push.prepare to get a presigned upload URL
5. Perform HTTP upload to the provided URL
6. Call push.finalize to create the release
7. Sync run ledgers (unless disabled)
8. Write a receipt file for audit trail

Usage

result, err := push.Push(ctx, push.Options{
    Remote:   "locktivity",
    PackPath: "packs/acme-prod.epack",
    Labels:   []string{"monthly", "soc2"},
})

Receipt Files

Push operations write receipt files to .epack/receipts/push/<remote>/<timestamp>_<digest>.json. These provide an audit trail of all push operations and include release information, synced runs, and client metadata.

Security

Remote adapters are verified against the lockfile when using source-based configuration. PATH-only adapters are unverified and should be used with caution. Authentication credentials are managed by the adapter, not this package.

Index

• type ClientReceipt
• type Options
• type PackReceipt
• type Receipt
  • func NewReceipt(remoteName string, target remote.TargetConfig, packPath string, ...) *Receipt
• type ReceiptWriter
  • func (w *ReceiptWriter) Write(receipt *Receipt) (string, error)
• type ReleaseReceipt
• type Result
  • func Push(ctx context.Context, opts Options) (*Result, error)
• type RunsReceipt
• type StepCallback
• type UploadProgressCallback

Types

type ClientReceipt

type ClientReceipt struct {
	EpackVersion string `json:"epack_version"`
	OS           string `json:"os"`
	Arch         string `json:"arch"`
}

ClientReceipt contains epack client metadata in the receipt.

type Options

type Options struct {
	// Secure defaults.
	Secure struct {
		Frozen bool
	}
	// Explicit insecure overrides.
	Unsafe struct {
		AllowUnpinned bool
	}

	// Remote is the name of the remote to push to (required).
	Remote string

	// PackPath is the path to the pack file (required).
	PackPath string

	// Environment is the environment override (optional).
	// Applies configuration from environments.<env> section.
	Environment string

	// Workspace overrides the target workspace (optional).
	Workspace string

	// Labels are release labels to apply (optional).
	Labels []string

	// Notes are release notes (optional).
	Notes string

	// RunsPaths are additional paths to search for run results (optional).
	RunsPaths []string

	// NoRuns disables automatic run syncing.
	NoRuns bool

	// NonInteractive disables interactive prompts.
	NonInteractive bool

	// Stderr is where adapter stderr output is written.
	// If nil, os.Stderr is used.
	Stderr io.Writer

	// OnStep is called when each step of the push workflow starts/completes.
	// Optional; if nil, no callbacks are made.
	OnStep StepCallback

	// OnUploadProgress is called periodically during upload.
	// Optional; if nil, no progress is reported.
	OnUploadProgress UploadProgressCallback

	// PromptInstallAdapter is called when the adapter is not installed.
	// If it returns true, the adapter will be installed automatically.
	// If nil, no prompt is shown and an error is returned instead.
	PromptInstallAdapter func(remoteName, adapterName string) bool
}

Options configures a push operation.

type PackReceipt

type PackReceipt struct {
	Path      string `json:"path"`
	Digest    string `json:"digest"`
	SizeBytes int64  `json:"size_bytes"`
}

PackReceipt contains pack metadata in the receipt.

type Receipt

type Receipt struct {
	// ReceiptVersion is the receipt format version.
	ReceiptVersion int `json:"receipt_version"`

	// CreatedAt is when the receipt was created.
	CreatedAt time.Time `json:"created_at"`

	// Remote is the remote name used for the push.
	Remote string `json:"remote"`

	// Target contains the workspace/environment.
	Target remote.TargetConfig `json:"target"`

	// Pack contains pack metadata.
	Pack PackReceipt `json:"pack"`

	// Release contains the release information from the remote.
	Release ReleaseReceipt `json:"release"`

	// Links contains URLs returned by the remote.
	Links map[string]string `json:"links,omitempty"`

	// Runs contains run syncing results.
	Runs RunsReceipt `json:"runs"`

	// Client contains epack client metadata.
	Client ClientReceipt `json:"client"`
}

Receipt records the result of a push operation for audit purposes.

func NewReceipt

func NewReceipt(
	remoteName string,
	target remote.TargetConfig,
	packPath string,
	packDigest string,
	packSize int64,
	release *remote.ReleaseResult,
	links map[string]string,
	syncedRuns []string,
	failedRuns []string,
) *Receipt

NewReceipt creates a new receipt from push result data.

type ReceiptWriter

type ReceiptWriter struct {
	// BaseDir is the base directory for receipts.
	// Defaults to .epack/receipts/push if empty.
	BaseDir string
}

ReceiptWriter writes push receipts to disk.

func (*ReceiptWriter) Write

func (w *ReceiptWriter) Write(receipt *Receipt) (string, error)

Write writes a receipt to disk. Returns the path to the written receipt file.

SECURITY: This function validates the remote name to prevent path traversal attacks and uses TOCTOU-safe file operations to prevent symlink attacks.

type ReleaseReceipt

type ReleaseReceipt struct {
	ReleaseID    string    `json:"release_id"`
	PackDigest   string    `json:"pack_digest"`
	CreatedAt    time.Time `json:"created_at"`
	CanonicalRef string    `json:"canonical_ref"`
}

ReleaseReceipt contains release information in the receipt.

type Result

type Result struct {
	// Release contains the release information from the remote.
	Release *remote.ReleaseResult

	// Links contains URLs returned by the remote.
	Links map[string]string

	// SyncedRuns lists run IDs that were successfully synced.
	SyncedRuns []string

	// FailedRuns lists run IDs that failed to sync.
	FailedRuns []string

	// ReceiptPath is the path to the written receipt file.
	ReceiptPath string
}

Result contains the result of a push operation.

func Push

func Push(ctx context.Context, opts Options) (*Result, error)

Push uploads a pack to a remote registry.

SECURITY: This function performs TOCTOU-safe execution for source-based adapters. The adapter binary is verified against the lockfile digest before execution, preventing attacks where an attacker modifies the binary between resolution and execution.

type RunsReceipt

type RunsReceipt struct {
	Synced []string `json:"synced"`
	Failed []string `json:"failed"`
}

RunsReceipt contains run syncing results in the receipt.

type StepCallback

type StepCallback func(step string, started bool)

StepCallback is called when a push step starts or completes. step is the step name, started indicates whether the step is starting (true) or done (false).

type UploadProgressCallback

type UploadProgressCallback func(written, total int64)

UploadProgressCallback is called periodically during upload with bytes written and total.