artifacts

package
v0.21.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package artifacts reads goreleaser's build manifest and says which of the things it produced belong on a release.

Why a manifest rather than a directory listing

goreleaser writes `dist/artifacts.json` describing every artefact it made, with a type for each. Globbing `dist/` instead would work today and change meaning silently the first time goreleaser's layout does, or the first time a repository adds a target — and it would happily publish intermediate build output alongside the archives.

Reading the manifest means an artefact colophon does not recognise is a visible failure rather than a silent inclusion.

What is NOT read from it

The manifest records where an artefact is on disk. It does not record where the bytes were uploaded to, because the upload is a separate goreleaser pipe. So the NAMES come from here and the location is built from the caller's upload target — which is colophon's own configuration rather than goreleaser's naming, and is the only part safe to construct.

Index

Constants

View Source
const ManifestFile = "artifacts.json"

ManifestFile is the name goreleaser always writes, inside its dist directory.

Variables

View Source
var ErrBadBase = errors.New("artifacts: the asset base must be an absolute http or https URL")

ErrBadBase reports a base that is not an absolute http or https URL.

View Source
var ErrCheckRefused = errors.New("artifacts: the check for an asset was refused")

ErrCheckRefused reports a check the server turned away, which says nothing about whether the asset is there.

View Source
var ErrNoPublishable = errors.New("artifacts: the manifest names nothing publishable")

ErrNoPublishable reports a manifest that parsed but named nothing a release should carry.

That is a failure rather than an empty success: a build that produced no archive has gone wrong, and publishing a release with no assets is the exact outcome this whole change exists to prevent.

View Source
var ErrNotThere = errors.New("artifacts: an asset is not at the location it would be published as")

ErrNotThere reports an asset that does not resolve where it was said to be.

View Source
var ErrUnreadable = errors.New("artifacts: cannot read the manifest")

ErrUnreadable reports a manifest that could not be read or parsed.

Functions

func Verify

func Verify(ctx context.Context, client Doer, located []Located, opts ...VerifyOption) error

Verify checks that every asset actually resolves before anything is published.

Why this is colophon's job and not the forge's

go/forge states it plainly: it records a location without fetching it, HEADing it or resolving it, because a request made on a caller's behalf to a host it does not control is a capability nobody asked for. Its guarantee is that no observer sees a release before its assets are attached — not that the bytes are there.

So a release can be published complete, correct by that contract, and every link on it 404. That is the ORIGINAL bug through a different door: the release exists, so a consumer is told yes and then gets a 404 that reads as a missing file rather than a race.

It also breaks the check this estate adopted for the first version of that bug. Counting a release's assets no longer distinguishes a good release from a bad one, because a broken one has a full set of links. Resolving one does.

colophon can make this check honestly because it is not a stranger to the address: it is publishing to a registry it just uploaded to. It sends no credential unless WithCredential gives it one, and then only to the forge.

Types

type Asset

type Asset struct {
	// Name is the filename as it should appear on the release.
	Name string

	// Kind is goreleaser's type for it, kept so a caller can report what it is
	// publishing rather than only how many.
	Kind string
}

Asset is one artefact that belongs on the release.

func Named added in v0.10.0

func Named(names []string) []Asset

Named turns a list of file names into the assets a release should carry.

The other half of Read: where that one learns from goreleaser what was built and filters it by type, this takes a project's own statement of what it publishes (spec 0017 D1). Both hand the same []Asset to Locate and Verify, which is why nothing downstream of here knows the difference.

These names are not filtered

Read's allow-list exists because goreleaser produces build output nobody wants on a release, and a type it invents tomorrow should not be published by accident. A named list has no such problem and gets no such protection: every entry is on the release because somebody wrote it down, which is the same reason this package reads a manifest rather than globbing a directory.

Kind is left EMPTY rather than given an invented value. It means "goreleaser said this was a Checksum", and there is no goreleaser here to have said it (spec 0017 D4).

func Read

func Read(dist string) ([]Asset, error)

Read returns the artefacts in dist that belong on a release, sorted by name so a release's assets do not reorder between runs for no reason.

type Doer

type Doer interface {
	Do(req *http.Request) (*http.Response, error)
}

Doer is the part of an HTTP client Verify needs. Injected so a test never reaches the network and never races on a package-level client.

type Located

type Located struct {
	Asset

	// URL is where the bytes live. It becomes the release asset's link.
	URL string
}

Located is an asset and the URL its bytes were uploaded to.

func Locate

func Locate(assets []Asset, base string) ([]Located, error)

Locate places each asset under base.

base is supplied rather than derived, and that is deliberate. colophon does not know where goreleaser was told to upload — that is goreleaser's own `uploads:` target — so guessing it would encode one tool's configuration inside another. The SAME value is written in both places, which makes a mismatch a configuration error a human can see rather than a silent 404.

type VerifyOption added in v0.15.0

type VerifyOption func(*verifier)

VerifyOption adjusts how Verify makes its attempts.

func WithCredential added in v0.21.3

func WithCredential(origin, token string) VerifyOption

WithCredential presents token as a Bearer token to assets on the forge's origin, and to nothing else, redirects included (spec 0033). An empty token sends nothing.

func WithWait added in v0.15.0

func WithWait(wait func(context.Context, time.Duration) error) VerifyOption

WithWait replaces the pause between attempts, which is how a test runs the retries without sleeping.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL