github

Documentation

Overview

Package github is the minimal GitHub REST client block needs: list the tags of a repository and fetch one release by tag. It deliberately avoids paging through /releases, which for projects that publish nightlies (Foundry has hundreds) would cost many requests per resolution.

Index

• Constants
• Variables
• type Asset
  • func (a Asset) SHA256() string
• type Client
  • func NewFromEnv(userAgent string) *Client
  • func (c *Client) Commit(ctx context.Context, repo, ref string) (string, error)
  • func (c *Client) Host() string
  • func (c *Client) Private(ctx context.Context, repo string) (bool, error)
  • func (c *Client) ReleaseByTag(ctx context.Context, repo, tag string) (*Release, error)
  • func (c *Client) Tags(ctx context.Context, repo, prefix string) ([]string, error)
• type Release
  • func (r *Release) AssetsNamed(name string) []Asset

Constants

const DefaultBaseURL = "https://api.github.com"

DefaultBaseURL is the public GitHub API.

const EnvBaseURL = "BLOCK_GITHUB_API_URL"

EnvBaseURL overrides the API base URL (used by tests and GitHub Enterprise).

Variables

var ErrNotFound = diag.UpstreamNotFound.Wrap(errors.New("not found"))

ErrNotFound reports a missing repository, tag or release.

Types

type Asset

type Asset struct {
	Name string `json:"name"`
	// URL is the asset's API endpoint, which serves the bytes when asked
	// for application/octet-stream. It is the only way to download an asset
	// of a private repository: BrowserDownloadURL answers a browser session
	// and nothing else.
	URL                string `json:"url"`
	BrowserDownloadURL string `json:"browser_download_url"`
	Size               int64  `json:"size"`
	// Digest is GitHub's own checksum of the upload, "sha256:<hex>", or ""
	// for assets uploaded before GitHub started recording it.
	Digest string `json:"digest"`
}

Asset is one downloadable release file.

func (Asset) SHA256

func (a Asset) SHA256() string

SHA256 returns the lower-case hex digest when GitHub recorded a sha256 for the asset, and "" otherwise — including when the field is present but is not a digest block could write into a lockfile and read back. A value that is not 64 hex characters is treated as absent rather than trusted, so that the caller downloads and hashes the artifact itself.

type Client

type Client struct {
	BaseURL   string
	Token     string
	HTTP      *http.Client
	UserAgent string
}

Client talks to the GitHub REST API.

func NewFromEnv

func NewFromEnv(userAgent string) *Client

NewFromEnv builds a client from BLOCK_GITHUB_API_URL and GITHUB_TOKEN/GH_TOKEN.

func (*Client) Commit

func (c *Client) Commit(ctx context.Context, repo, ref string) (string, error)

Commit returns the full SHA of the commit a tag (or any ref) points at. GitHub dereferences annotated tags for this endpoint.

func (*Client) Host

func (c *Client) Host() string

Host is the host the client sends its token to, as it appears in BaseURL.

func (*Client) Private

func (c *Client) Private(ctx context.Context, repo string) (bool, error)

Private reports whether repo is a private repository. A client without a token is shown public repositories only, so anything it resolved is public and no request is spent asking.

func (*Client) ReleaseByTag

func (c *Client) ReleaseByTag(ctx context.Context, repo, tag string) (*Release, error)

ReleaseByTag fetches the release published for tag. A tag without a release yields ErrNotFound.

func (*Client) Tags

func (c *Client) Tags(ctx context.Context, repo, prefix string) ([]string, error)

Tags lists the repository's tag names starting with prefix, once each, in the order GitHub returns them (lexically ordered refs).

The matching-refs endpoint does not always honour ?page: for some repositories it answers every page with the same full list, so paging blindly would repeat each tag as many times as there are pages — and the caller would then spend its release lookups on the same tag over and over. A page that contributes no new tag therefore ends the walk.

type Release

type Release struct {
	TagName    string  `json:"tag_name"`
	Draft      bool    `json:"draft"`
	Prerelease bool    `json:"prerelease"`
	Assets     []Asset `json:"assets"`
}

Release is the subset of a GitHub release block consumes.

func (*Release) AssetsNamed

func (r *Release) AssetsNamed(name string) []Asset

AssetsNamed returns every asset of the release with this file name.

It returns a list rather than "the" asset because a release carrying two files of one name is not something to resolve by taking the first: the two are different downloads, and which one a lockfile pinned would depend on the order the API happened to answer in. The caller refuses that instead.