ci

type Actor struct {
	// Handle is the platform login, where the platform reports one.
	Handle string `json:"handle,omitempty" yaml:"handle,omitempty"`
	// Name is a display name, which is not unique: two people can share one.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// ID is the platform's stable identifier for the account, which is what makes the record
	// unambiguous where a handle is missing or a name is shared.
	ID string `json:"id,omitempty" yaml:"id,omitempty"`
	// Email is set only when the descriptor asked for it (`config.ci.recordEmail`). It is
	// personal data, so the default is not to read it at all.
	Email string `json:"email,omitempty" yaml:"email,omitempty"`
}

type Context struct {
	// System names the platform: "github-actions", "gitlab-ci", "azure-pipelines", "circleci",
	// "buildkite".
	System string `json:"system" yaml:"system"`
	// Repository is the repository the pipeline is for, in the platform's own spelling.
	Repository string `json:"repository,omitempty" yaml:"repository,omitempty"`
	// Ref is the branch or tag being built.
	Ref string `json:"ref,omitempty" yaml:"ref,omitempty"`
	// Workflow and Job locate the scan within the pipeline. A repository usually has several
	// pipelines and a pipeline several jobs, so neither identifies it alone.
	Workflow string `json:"workflow,omitempty" yaml:"workflow,omitempty"`
	Job      string `json:"job,omitempty" yaml:"job,omitempty"`
	// RunID is the platform's identifier for this run, and Attempt distinguishes a retry of a
	// failed run from a fresh one. Together they are what a run key is derived from.
	//
	// Attempt is set only where the platform reuses the run id across attempts, which today is
	// GitHub Actions. Elsewhere a retry already has an id of its own and qualifying it further
	// would make every first attempt look like a retry.
	RunID   string `json:"runId,omitempty" yaml:"runId,omitempty"`
	Attempt string `json:"attempt,omitempty" yaml:"attempt,omitempty"`
	// URL is where a person can go and read the job's own logs. Absent where the platform does not
	// publish enough to build one. A guessed URL is worse than none.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`

	// RunBy is who the platform reports as having started the pipeline, and CommitAuthor who it
	// reports as having written the commit being built. Two fields because they are usually two
	// people: for a suppression, one wrote the line and the other pressed a button, and a trail
	// that folds them together cannot say which it is showing.
	//
	// Both are what the CI system reported, not an identity anybody verified. A pipeline controls
	// its own environment, so these are a lead to follow and never evidence of who acted. Absent
	// where the platform does not say; neither is ever filled in from the other.
	RunBy        *Actor `json:"runBy,omitempty" yaml:"runBy,omitempty"`
	CommitAuthor *Actor `json:"commitAuthor,omitempty" yaml:"commitAuthor,omitempty"`
	// TriggeredBy is set only when a re-run was started by somebody other than RunBy, which on
	// GitHub keeps the original actor in GITHUB_ACTOR. A re-run by somebody else is the case an
	// auditor asks about.
	TriggeredBy *Actor `json:"triggeredBy,omitempty" yaml:"triggeredBy,omitempty"`
}