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 New(info clive.Info, opts ...Option) Config
  • func (c Config) BinaryName() string
  • func (c Config) Check(ctx context.Context) error
  • func (c Config) DisplayName() string
  • func (c Config) LatestRef(ctx context.Context, _ *http.Client) (string, error)
  • func (c Config) Update(ctx context.Context, dev, _ bool) error
  • func (c Config) VersionLink(v string) string
• type Option
  • func WithBinary(binary string) Option
  • func WithChecksumFile(name string) Option
  • func WithEnterpriseURL(url string) Option
  • func WithFilters(filters ...string) Option
  • func WithInstallDirectory(dir string) Option
  • func WithName(name string) Option
  • func WithPrerelease() Option
  • func WithSkipChecksum() Option
  • func WithTokenEnv(env string) Option
  • func WithUniversalArch(arch string) Option

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 {
	// contains filtered or unexported fields
}

Config identifies the tool for a GitHub release-asset self-update. Build it with New: the info (a GitHub repo via Info.Repo or a github.com module) is required, and optional behaviour is set with the With* [Option]s. It satisfies updater.Tool for notify.

func New

func New(info clive.Info, opts ...Option) Config

New builds a Config for a GitHub release-asset self-update. info carries the GitHub repo (Info.Repo, or a github.com Info.Module) used to locate releases and build version links. Optional behaviour is configured with the With* [Option]s.

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

func (c Config) Check(ctx context.Context) error

Check implements updater.Updater.

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

func (c Config) Update(ctx context.Context, dev, _ bool) error

Update implements updater.Updater; dev selects the newest prerelease and stable is ignored (Latest already is the latest stable release).

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.

type Option

type Option func(*Config)

Option customises a Config built by New.

func WithBinary

func WithBinary(binary string) Option

WithBinary sets the executable name located inside a downloaded archive and installed into the install directory; it defaults to the repo (or module) name.

func WithChecksumFile

func WithChecksumFile(name string) Option

WithChecksumFile sets the name of the combined checksums asset verified against the download, for a release that names it other than goreleaser's default "checksums.txt". Ignored when checksum verification is skipped.

func WithEnterpriseURL

func WithEnterpriseURL(url string) Option

WithEnterpriseURL sets the API base URL of a GitHub Enterprise instance, e.g. "https://ghe.example.com/api/v3/"; releases and the gh token are then resolved for that host rather than github.com.

func WithFilters

func WithFilters(filters ...string) Option

WithFilters sets regexps 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.

func WithInstallDirectory

func WithInstallDirectory(dir string) Option

WithInstallDirectory sets the directory the binary is installed into. A leading "~" and any $ENV references are expanded; it defaults to ~/.local/bin.

func WithName

func WithName(name string) Option

WithName sets the human-facing display name shown in messages; it defaults to the binary (and thus repo) name.

func WithPrerelease

func WithPrerelease() Option

WithPrerelease makes the default channel (used by Check and the notify integration) consider prereleases.

func WithSkipChecksum

func WithSkipChecksum() Option

WithSkipChecksum disables sha256 verification of the downloaded asset against a published checksums file. Verification is on by default.

func WithTokenEnv

func WithTokenEnv(env string) Option

WithTokenEnv names an environment variable consulted before the gh CLI's stored credentials for a GitHub token; it defaults to "GITHUB_TOKEN".

func WithUniversalArch

func WithUniversalArch(arch string) Option

WithUniversalArch sets the architecture name of a macOS universal binary asset (e.g. "all"); that asset is chosen when none matches the host's specific arch.