github

Documentation

Overview

Package github self-updates a Go CLI binary from its GitHub releases. A tool describes itself with a Config and calls Update, which resolves the latest release, picks the asset matching the host OS/arch, downloads and extracts the binary, and installs it into a directory (default ~/.local/bin). Check reports whether a newer release exists without installing anything.

The release discovery, OS/arch asset matching, archive extraction, checksum validation, and rollback-safe replacement are done by github.com/creativeprojects/go-selfupdate; this package is a thin wrapper that gives a github-distributed tool the same Config/updater.Tool interface, clog UX, install-directory default, and notify integration as updater/brew and updater/goinstall. Private repositories work by piggybacking on the gh CLI's stored credentials (github.com/cli/go-gh) for the API token.

Index

• func Check(ctx context.Context, cfg Config) error
• func Update(ctx context.Context, cfg Config, channel Channel) error
• type Channel
  • func ChannelFor(prerelease bool) Channel
• type Config
  • func (c Config) BinaryName() string
  • func (c Config) DisplayName() string
  • func (c Config) LatestRef(ctx context.Context, _ *http.Client) (string, error)
  • func (c Config) VersionLink(v string) string

Functions

func Check

func Check(ctx context.Context, cfg Config) error

Check reports whether a newer release of cfg is available, without installing. It queries the GitHub releases API directly rather than the module proxy, so a binary distributed only as a release asset - or from a private repo - can call it without a Go toolchain on PATH.

func Update

func Update(ctx context.Context, cfg Config, channel Channel) error

Update installs the latest cfg from its GitHub releases on the given channel.

Types

type Channel

type Channel int

Channel selects which release Update installs.

const (
	// Latest installs the newest published, non-prerelease release; the default.
	Latest Channel = iota
	// Prerelease installs the newest release including prereleases.
	Prerelease
)

func ChannelFor

func ChannelFor(prerelease bool) Channel

ChannelFor maps a --pre flag to a Channel; unset is Latest.

type Config

type Config struct {
	// Binary is the executable name located inside a downloaded archive and
	// installed into Dir. Defaults to the repo (or module) name.
	Binary string
	// ChecksumFile is the name of the combined checksums asset verified against the
	// download, for a release that names it other than goreleaser's default.
	// Defaults to "checksums.txt". Ignored when SkipChecksum is set.
	ChecksumFile string
	// Dir is the directory the binary is installed into. A leading "~" and any
	// $ENV references are expanded. Defaults to ~/.local/bin.
	Dir string
	// EnterpriseURL is the API base URL of a GitHub Enterprise instance, e.g.
	// "https://ghe.example.com/api/v3/". When set, releases are fetched from there
	// and the gh token is resolved for that host rather than github.com. Empty uses
	// public github.com.
	EnterpriseURL string
	// Filters are optional regexp matched against asset names, to disambiguate a
	// release that publishes several assets for the same OS/arch. An asset must
	// match one of them in addition to the OS/arch/extension matching.
	Filters []string
	// Info carries the repo ("owner/name", via Info.Repo or a github.com
	// Info.Module) used to query releases and build version links.
	Info clive.Info
	// Name is the display name shown in messages. Defaults to the binary name.
	Name string
	// Prerelease makes the default channel (used by Check and the notify
	// integration) consider prereleases.
	Prerelease bool
	// SkipChecksum disables sha256 verification of the downloaded asset against a
	// published checksums file. Verification is on by default.
	SkipChecksum bool
	// TokenEnv names an environment variable consulted before the gh CLI's stored
	// credentials for a GitHub token. Defaults to "GITHUB_TOKEN".
	TokenEnv string
	// UniversalArch is the architecture name of a macOS universal binary asset
	// (e.g. "all"); when set, that asset is chosen if none matches the host's
	// specific arch.
	UniversalArch string
}

Config identifies the tool for a GitHub release-asset self-update. Either Info.Repo or a github.com Info.Module is required to locate releases; everything else has a sensible default.

func (Config) BinaryName

func (c Config) BinaryName() string

BinaryName is the executable/command name, defaulting to the repo (or module) name. It is also the name go-selfupdate looks for inside a downloaded archive.

func (Config) DisplayName

func (c Config) DisplayName() string

DisplayName is the human-facing name used in messages, defaulting to the binary (and thus the repo) name when Name is unset.

func (Config) LatestRef

func (c Config) LatestRef(ctx context.Context, _ *http.Client) (string, error)

LatestRef returns the latest release's tag, letting Config satisfy updater.Tool so a github-distributed tool feeds notify the same "latest" the updater installs. The client is unused: go-selfupdate manages its own HTTP.

func (Config) VersionLink

func (c Config) VersionLink(v string) string

VersionLink renders v as a clickable link to its release or commit, delegating to the embedded clive.Info. It lets Config satisfy updater.Tool.