docspreview

package
v0.72.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 31, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package docspreview owns the docs-preview screenshots branch and sticky comment mutation policy used by GitHub Actions.

Index

Constants

View Source
const (
	ScreenshotsBranch = "screenshots"
	StickyMarker      = "<!-- docs-preview -->"
	DefaultMaxAge     = 30 * 24 * time.Hour

	// EmptyTreeSHA is git's well-known empty tree. The GitHub API rejects
	// createTree with an empty tree slice, so destructive rewrites that keep no
	// files commit this tree directly.
	EmptyTreeSHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
)

Variables

This section is empty.

Functions

func BuildRewriteCommit

func BuildRewriteCommit(ctx context.Context, client TreeWriter, repo Repository, kept []TreeEntry, parentSHA, message string) (string, error)

func Cleanup

func Cleanup(ctx context.Context, options CleanupOptions) error

func IsSameRepoPR

func IsSameRepoPR(event Event, repo Repository) bool

IsSameRepoPR fails closed for deleted/fork heads. Fork PR tokens are read-only even when workflow permissions request writes, and publish runs from PR-controlled code for same-repo PRs only.

func IsStaleRunDir

func IsStaleRunDir(path string, now time.Time, maxAge time.Duration) bool

func Prune

func Prune(ctx context.Context, options PruneOptions) error

func Publish

func Publish(ctx context.Context, options PublishOptions) error

Types

type BlobWriter

type BlobWriter interface {
	CreateBlob(ctx context.Context, owner, repo string, content, encoding string) (string, error)
}

type BranchClient

type BranchClient interface {
	GetRef(ctx context.Context, owner, repo, ref string) (Ref, error)
	CreateRef(ctx context.Context, owner, repo, ref, sha string) error
	UpdateRef(ctx context.Context, owner, repo, ref, sha string) error
	GetCommit(ctx context.Context, owner, repo, sha string) (Commit, error)
}

type BranchResult

type BranchResult struct {
	Outcome  string
	Attempts int
}

func CommitToBranch

func CommitToBranch(ctx context.Context, options CommitToBranchOptions) (BranchResult, error)

type BranchTip

type BranchTip struct {
	CommitSHA string
	TreeSHA   string
}

type CleanupClient

type CleanupClient interface {
	BranchClient
	TreeReader
	TreeWriter
	CommentClient
}

type CleanupOptions

type CleanupOptions struct {
	Client CleanupClient
	Logger Logger
	Repo   Repository
	Event  Event
}

type Comment

type Comment struct {
	ID   int64
	Body string
}

type CommentClient

type CommentClient interface {
	ListComments(ctx context.Context, owner, repo string, issueNumber int) ([]Comment, error)
	UpdateComment(ctx context.Context, owner, repo string, commentID int64, body string) error
	CreateComment(ctx context.Context, owner, repo string, issueNumber int, body string) error
}

type Commit

type Commit struct {
	SHA     string
	TreeSHA string
	Parents []string
	Message string
}

type CommitToBranchOptions

type CommitToBranchOptions struct {
	Client         BranchClient
	Logger         Logger
	Repo           Repository
	CreateIfAbsent bool
	MaxAttempts    int
	BuildCommit    func(context.Context, *BranchTip) (string, error)
}

type Event

type Event struct {
	Repository  EventRepository `json:"repository"`
	PullRequest *PullRequest    `json:"pull_request"`
}

type EventOwner

type EventOwner struct {
	Login string `json:"login"`
	Name  string `json:"name"`
}

type EventRepository

type EventRepository struct {
	FullName string     `json:"full_name"`
	Name     string     `json:"name"`
	Owner    EventOwner `json:"owner"`
}

type GitHubHTTPClient

type GitHubHTTPClient struct {
	Client  *http.Client
	BaseURL string
	Token   string
}

func (*GitHubHTTPClient) CreateBlob

func (client *GitHubHTTPClient) CreateBlob(ctx context.Context, owner, repo string, content, encoding string) (string, error)

func (*GitHubHTTPClient) CreateComment

func (client *GitHubHTTPClient) CreateComment(ctx context.Context, owner, repo string, issueNumber int, body string) error

func (*GitHubHTTPClient) CreateCommit

func (client *GitHubHTTPClient) CreateCommit(ctx context.Context, owner, repo string, message, tree string, parents []string) (string, error)

func (*GitHubHTTPClient) CreateRef

func (client *GitHubHTTPClient) CreateRef(ctx context.Context, owner, repo, ref, sha string) error

func (*GitHubHTTPClient) CreateTree

func (client *GitHubHTTPClient) CreateTree(ctx context.Context, owner, repo string, entries []TreeEntry, baseTree string) (string, error)

func (*GitHubHTTPClient) GetCommit

func (client *GitHubHTTPClient) GetCommit(ctx context.Context, owner, repo, sha string) (Commit, error)

func (*GitHubHTTPClient) GetRef

func (client *GitHubHTTPClient) GetRef(ctx context.Context, owner, repo, ref string) (Ref, error)

func (*GitHubHTTPClient) GetTree

func (client *GitHubHTTPClient) GetTree(ctx context.Context, owner, repo, sha string, recursive bool) (Tree, error)

func (*GitHubHTTPClient) ListComments

func (client *GitHubHTTPClient) ListComments(ctx context.Context, owner, repo string, issueNumber int) ([]Comment, error)

func (*GitHubHTTPClient) UpdateComment

func (client *GitHubHTTPClient) UpdateComment(ctx context.Context, owner, repo string, commentID int64, body string) error

func (*GitHubHTTPClient) UpdateRef

func (client *GitHubHTTPClient) UpdateRef(ctx context.Context, owner, repo, ref, sha string) error

type Logger

type Logger interface {
	Info(message string)
}

type PreviewEntry

type PreviewEntry struct {
	Kind string `json:"kind"`
	File string `json:"file,omitempty"`
}

type PreviewManifest

type PreviewManifest map[string]map[string]PreviewEntry

type PruneClient

type PruneClient interface {
	BranchClient
	TreeReader
	TreeWriter
}

type PruneOptions

type PruneOptions struct {
	Client PruneClient
	Logger Logger
	Repo   Repository
	Now    time.Time
	MaxAge time.Duration
}

type PublishClient

type PublishClient interface {
	BranchClient
	TreeWriter
	BlobWriter
	CommentClient
}

type PublishOptions

type PublishOptions struct {
	Client       PublishClient
	Logger       Logger
	Repo         Repository
	Event        Event
	ManifestPath string
	AssetsDir    string
	SHA          string
	RunID        string
	RunAttempt   string
	Now          time.Time
}

type PullBaseRef

type PullBaseRef struct {
	Ref string `json:"ref"`
	SHA string `json:"sha"`
}

type PullRef

type PullRef struct {
	Repo *PullRepository `json:"repo"`
}

type PullRepository

type PullRepository struct {
	FullName string `json:"full_name"`
}

type PullRequest

type PullRequest struct {
	Number int         `json:"number"`
	Head   PullRef     `json:"head"`
	Base   PullBaseRef `json:"base"`
}

type Ref

type Ref struct {
	SHA string
}

type Repository

type Repository struct {
	Owner string
	Name  string
}

func ParseRepository

func ParseRepository(value string) (Repository, error)

func RepositoryFromEvent

func RepositoryFromEvent(event Event) (Repository, error)

func (Repository) FullName

func (repo Repository) FullName() string

type StatusError

type StatusError struct {
	Status  int
	Message string
}

func (*StatusError) Error

func (err *StatusError) Error() string

type Tree

type Tree struct {
	SHA       string
	Entries   []TreeEntry
	Truncated bool
}

type TreeEntry

type TreeEntry struct {
	Path string `json:"path"`
	Mode string `json:"mode"`
	Type string `json:"type"`
	SHA  string `json:"sha"`
}

func ListBlobsOrFail

func ListBlobsOrFail(ctx context.Context, client TreeReader, repo Repository, treeSHA string) ([]TreeEntry, error)

type TreeReader

type TreeReader interface {
	GetTree(ctx context.Context, owner, repo, sha string, recursive bool) (Tree, error)
}

type TreeWriter

type TreeWriter interface {
	CreateTree(ctx context.Context, owner, repo string, entries []TreeEntry, baseTree string) (string, error)
	CreateCommit(ctx context.Context, owner, repo string, message, tree string, parents []string) (string, error)
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL