actionref

Documentation

Overview

Package actionref resolves an action that a step's `uses` names outside Probe to the executable that serves it.

Such an action is published in a GitHub repository and pinned to a commit:

uses: github.com/<owner>/<repo>[/<dir>]@<40-character commit SHA>

or lives in a local directory:

uses: ./path/to/action

Either way the directory holds an action.yml that says which executable serves the action. The executable speaks the protocol in package actionrpc.

Index

• Constants
• func IsExternal(uses string) bool
• func Release(manifest []byte, tag string, checksums io.Reader) ([]byte, error)
• func Scaffold(repo string) ([]byte, error)
• type Executable
  • func Resolve(uses, baseDir string) (*Executable, error)
• type Manifest
  • func ParseManifest(data []byte) (*Manifest, error)
  • func ReadManifest(uses, baseDir string) (*Manifest, error)
• type Ref
  • func Parse(uses string) (Ref, error)
• type Resolver
  • func (r *Resolver) Manifest(uses, baseDir string) (*Manifest, error)
  • func (r *Resolver) Resolve(uses, baseDir string) (*Executable, error)
• type Runs

Constants

const ManifestFile = "action.yml"

ManifestFile is the file in an action's directory that describes it.

const UsingBinary = "binary"

UsingBinary is the only kind of action an action.yml can describe: an executable that serves the action over the actionrpc protocol.

Functions

func IsExternal

func IsExternal(uses string) bool

IsExternal reports whether uses names an action outside Probe. No built-in action has a slash in its name.

func Release

func Release(manifest []byte, tag string, checksums io.Reader) ([]byte, error)

Release returns the action.yml of the release tag from the action.yml of the release before it: runs.url names the same asset under tag, and runs.checksums are the digests that checksums lists for that asset. What else the action.yml declares is kept, so it stays the one place an action is described in.

checksums is what sha256sum or GoReleaser writes, a line of which is "<digest> <file>". A line is taken when its file is the asset runs.url names, with a platform in place of {os} and {arch}; any other is left out.

The result is written in one form whatever form manifest has. The comment lines manifest starts with are kept, and no other comment is.

func Scaffold

func Scaffold(repo string) ([]byte, error)

Scaffold returns an action.yml to start a new action from, for the GitHub repository repo, as <owner>/<repo>, that will publish it. It names the action after the repository, without a leading "probe-", and the executable of each platform <repo>_{os}_{arch}, which is what GoReleaser names an unarchived one by default. It has no checksums: Release adds those of the first release.

Types

type Executable

type Executable struct {
	// Path is the executable's location on this machine.
	Path string
	// SHA256 is the digest the executable must have when it is started, or
	// empty for a local action that does not pin one.
	SHA256 []byte
}

Executable is the program that serves an action.

func Resolve

func Resolve(uses, baseDir string) (*Executable, error)

Resolve resolves uses with a Resolver shared by the whole process.

type Manifest

type Manifest struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
	Runs        Runs   `yaml:"runs"`
	// Guard are the kinds of guard the action keeps to itself, such as
	// read-only and allow-host. Probe takes the action at its word and runs
	// it under a guard of those kinds; a kind Probe does not know is left
	// alone, so the action is refused under a guard it does not name.
	Guard []string `yaml:"guard"`
	// Params are the keys the action takes in with, for probe check to
	// check a step's with against. Nil, when action.yml does not say, takes
	// any key.
	Params []string `yaml:"params"`
}

Manifest is the content of an action.yml.

func ParseManifest

func ParseManifest(data []byte) (*Manifest, error)

ParseManifest parses the content of an action.yml.

func ReadManifest

func ReadManifest(uses, baseDir string) (*Manifest, error)

ReadManifest reads the action.yml of uses with the Resolver shared by the whole process, which Resolve then uses for the same action.

type Ref

type Ref struct {
	// Local is the directory of a local action, as written. The other fields
	// are empty when it is set.
	Local string
	// Owner and Repo name the GitHub repository of a remote action.
	Owner string
	Repo  string
	// Dir is the directory of the action within the repository, slash
	// separated, or empty for the repository root.
	Dir string
	// SHA is the commit the action is pinned to.
	SHA string
}

Ref is a parsed `uses` that names an external action.

func Parse

func Parse(uses string) (Ref, error)

Parse parses uses as a reference to an external action.

type Resolver

type Resolver struct {
	// CacheDir is where downloaded actions are kept. It defaults to probe/actions
	// under the user's cache directory.
	CacheDir string
	// Client fetches action.yml files and executables. It defaults to a client
	// with a five-minute timeout.
	Client *http.Client
	// RawBaseURL is where file contents of a GitHub repository are served. It
	// defaults to https://raw.githubusercontent.com.
	RawBaseURL string
	// OS and Arch are the platform to resolve for. They default to the
	// platform Probe runs on.
	OS   string
	Arch string
	// contains filtered or unexported fields
}

Resolver finds and downloads the executables of external actions. A Resolver remembers what it resolved, so an action is fetched once however many steps use it. Its zero value is ready to use.

func (*Resolver) Manifest

func (r *Resolver) Manifest(uses, baseDir string) (*Manifest, error)

Manifest returns the action.yml of the external action uses names, without fetching its executable, so that what it declares can be read before it is run. A remote one is read at the pinned commit.

func (*Resolver) Resolve

func (r *Resolver) Resolve(uses, baseDir string) (*Executable, error)

Resolve returns the executable of the external action uses names. A local action's path is taken relative to baseDir, or to the working directory when baseDir is empty.

type Runs

type Runs struct {
	// Using is the kind of action. It must be "binary".
	Using string `yaml:"using"`
	// URL is where the executable is downloaded from. {os} and {arch} are
	// replaced with the GOOS and GOARCH of the machine running Probe.
	URL string `yaml:"url"`
	// Path is the executable relative to the action's directory, with the
	// same placeholders as URL. Only a local action can use it.
	Path string `yaml:"path"`
	// Checksums maps "<os>_<arch>" to the SHA-256 digest of the executable
	// for that platform, in hex. A URL needs one for the running platform.
	Checksums map[string]string `yaml:"checksums"`
}

Runs says how an action is run.