artifact

Documentation

Index

• Constants
• Variables
• func WritePublishManifest(dir string, manifest PublishManifest) error
• type AttestationRecord
• type AttestationType
• type BuildInstance
• type PublishManifest
  • func ReadPublishManifest(dir string) (*PublishManifest, error)
• type PublishedArchive
• type PublishedBinary
• type PublishedImage

Constants

const PublishManifestPath = ".stagefreight/publish.json"

Variables

var ErrPublishManifestInvalid = errors.New("publish manifest invalid")

var ErrPublishManifestNotFound = errors.New("publish manifest not found")

Functions

func WritePublishManifest

func WritePublishManifest(dir string, manifest PublishManifest) error

WritePublishManifest writes the publish manifest and its SHA-256 checksum sidecar. Canonicalizes Ref, deduplicates by host/path:tag, sorts deterministically, and sets timestamp if empty.

Types

type AttestationRecord

type AttestationRecord struct {
	Type           AttestationType `json:"type,omitempty"`
	SignatureRef   string          `json:"signature_ref,omitempty"`   // cosign signature digest ref
	AttestationRef string          `json:"attestation_ref,omitempty"` // DSSE provenance digest ref
	SignerIdentity string          `json:"signer_identity,omitempty"` // workload identity / key fingerprint
	VerifiedDigest string          `json:"verified_digest,omitempty"` // digest the signature covers
}

AttestationRecord captures signing and attestation metadata for a published image.

type AttestationType

type AttestationType string

AttestationType identifies the signing/attestation mechanism.

const (
	AttestationCosign AttestationType = "cosign"
	AttestationInToto AttestationType = "in-toto"
	AttestationSLSA   AttestationType = "slsa"
)

type BuildInstance

type BuildInstance struct {
	Commit     string `json:"commit,omitempty"`
	PipelineID string `json:"pipeline_id,omitempty"`
	JobID      string `json:"job_id,omitempty"`
	CreatedAt  string `json:"created_at,omitempty"`
}

BuildInstance captures CI/build environment metadata for provenance.

type PublishManifest

type PublishManifest struct {
	Published []PublishedImage   `json:"published"`
	Binaries  []PublishedBinary  `json:"binaries,omitempty"`
	Archives  []PublishedArchive `json:"archives,omitempty"`
	Timestamp string             `json:"timestamp"` // RFC3339
}

PublishManifest records all artifacts successfully produced during a build.

func ReadPublishManifest

func ReadPublishManifest(dir string) (*PublishManifest, error)

ReadPublishManifest reads and validates the publish manifest and its checksum.

type PublishedArchive

type PublishedArchive struct {
	Name     string          `json:"name"`   // archive filename
	Format   string          `json:"format"` // tar.gz | zip
	Path     string          `json:"path"`   // local archive path
	Size     int64           `json:"size"`
	SHA256   string          `json:"sha256"`
	Contents []string        `json:"contents,omitempty"` // files in archive
	BuildID  string          `json:"build_id"`
	Binary   PublishedBinary `json:"binary"`
}

PublishedArchive records a single archive that was successfully created.

type PublishedBinary

type PublishedBinary struct {
	Name      string `json:"name"` // logical binary name
	OS        string `json:"os"`
	Arch      string `json:"arch"`
	Path      string `json:"path"` // local binary path
	Size      int64  `json:"size"`
	SHA256    string `json:"sha256"`
	BuildID   string `json:"build_id"`
	Version   string `json:"version,omitempty"`
	Commit    string `json:"commit,omitempty"`
	Toolchain string `json:"toolchain,omitempty"` // "go1.24.1" — for audit + crucible verification
}

PublishedBinary records a single binary that was successfully built.

type PublishedImage

type PublishedImage struct {
	Host              string             `json:"host"`                          // normalized registry host
	Path              string             `json:"path"`                          // image path
	Tag               string             `json:"tag"`                           // resolved tag
	Provider          string             `json:"provider"`                      // canonical provider name
	Ref               string             `json:"ref"`                           // full image ref (host/path:tag)
	Digest            string             `json:"digest,omitempty"`              // image digest (immutable truth)
	CredentialRef     string             `json:"credential_ref,omitempty"`      // non-secret env var prefix for OCI auth resolution
	BuildInstance     BuildInstance      `json:"build_instance,omitempty"`      // CI/build metadata
	Registry          string             `json:"registry,omitempty"`            // registry hostname
	ObservedDigest    string             `json:"observed_digest,omitempty"`     // what the registry returned post-push
	ObservedDigestAlt string             `json:"observed_digest_alt,omitempty"` // second observation via registry API
	ObservedBy        string             `json:"observed_by,omitempty"`         // primary observation method (e.g., "buildx")
	ObservedByAlt     string             `json:"observed_by_alt,omitempty"`     // alternate observation method (e.g., "registry_api")
	ExpectedTags      []string           `json:"expected_tags,omitempty"`       // all tags this digest was published under
	ExpectedCommit    string             `json:"expected_commit,omitempty"`     // commit this digest was built from
	Attestation       *AttestationRecord `json:"attestation,omitempty"`         // signing/attestation record (nil = absent)
	SigningAttempted  bool               `json:"signing_attempted,omitempty"`   // true if signing was attempted but failed
}

PublishedImage records a single image that was successfully pushed.