ci_tip.go RawHistoryFolder

1// SPDX-License-Identifier: AGPL-3.0-or-later
2
3package domain
4
5// CIRefTip records who moves a branch or a tag to an object (CI-3, D1): the
6// actor and pusher of the push or merge that sets Ref to Sha, and whether that
7// principal was trusted (TrustedActor).
8//
9// It is what a scheduled run takes its actor and its trust from (GitHub runs a
10// schedule as the author of the last commit of the default branch), and what a
11// dispatched run's trust is capped by: the default branch is not necessarily
12// the owner's work (a token limited to some branches can push the first branch
13// of an empty repository, which becomes the default branch), and an agent's
14// branch is not the owner's work either.
15//
16// The record is written BEFORE the ref moves (in the pre-receive decision of a
17// push, and inside the merge before it updates the target), so that no moment
18// exists when the tip is the new commit and its record the previous pusher's;
19// writing it after would let a slow post-receive of an agent's push leave the
20// owner's record on a tip the agent has since moved back to the same commit
21// (owner A, agent B, agent A). It names the object it was written for, and is
22// valid only while the ref still points to it. A push that is refused after the
23// record was written leaves a record that matches no tip: not trusted (fails
24// closed). A tip with no record (a push from before records existed, a record
25// that could not be written) is not trusted either.
26//
27// Two concurrent pushes of the same object by the owner and by an agent can
28// leave the owner's record: the object is the same and the owner pushed it, so
29// the content is endorsed by the owner. That case is accepted.
30type CIRefTip struct {
31	Repo RepoName
32	// Ref is the full name: "refs/heads/main" or "refs/tags/v1".
33	Ref string
34	// Sha is the object the ref is set to (the tag object for an annotated tag).
35	Sha string
36	// Actor is who the run shows, as for a push (authorOf).
37	Actor string
38	// Pusher is the principal whose rights the actions of other repositories are
39	// resolved with.
40	Pusher  CIPusher
41	Trusted bool
42}