gitsync

package
v0.21.1 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 42 Imported by: 0

Documentation

Overview

Package gitsync keeps git-bound skills in step with their repositories through one GitHub App per instance.

Index

Constants

View Source
const (
	DefaultWebBaseURL = "https://github.com"
	DefaultAPIBaseURL = "https://api.github.com"
)

Public GitHub. An Enterprise Server names its own pair.

View Source
const (
	ContestOff       = "off"
	ContestOnRequest = "on_request"
	ContestReady     = "ready"
)

Contest settings of a connection.

View Source
const (
	KindAdopt   = "adopt"   // imported earlier from this repo and path
	KindMatch   = "match"   // same name, another origin
	KindNew     = "new"     // a name the registry does not have
	KindRefused = "refused" // outside the prefix, a duplicate, or bound elsewhere
)

Preview kinds.

View Source
const ContestLabel = "skael:contest"

ContestLabel on a pull request asks for a contest. Adding a label needs write access to the repo, so it is a request a stranger cannot make.

View Source
const SyncInterval = time.Minute

SyncInterval is how often every connection is compared with its branch. A webhook only brings that comparison forward.

View Source
const WebhookPath = "/api/github/webhook"

WebhookPath is where GitHub delivers the App's events. The auth middleware passes it: the signature is the authentication.

Variables

View Source
var ErrAppExists = errors.New("this instance already has a GitHub App; disconnect it first")

ErrAppExists means the instance already has an App.

View Source
var ErrForbidden = errors.New("only an admin or an owner of the prefix can connect a repo to it")

ErrForbidden means the person may not change the ownership rule for the prefix.

View Source
var ErrManifestState = errors.New("the GitHub App setup expired or did not start here; start it again")

ErrManifestState means GitHub returned a state this instance did not issue, or one that expired.

View Source
var ErrNoApp = errors.New("connect GitHub first: this instance has no GitHub App")

ErrNoApp means the instance has no GitHub App yet.

View Source
var ErrNotFound = errors.New("not found on GitHub, or the App cannot see it")

ErrNotFound is GitHub's 404: a missing repo, branch or installation, or one the App cannot see.

View Source
var ErrSealed = errors.New("the GitHub App's secrets do not open with the current master key")

ErrSealed means a stored App secret does not open with any master key.

Functions

func Manifest

func Manifest(r ManifestRequest, state string) (postURL string, manifest string, err error)

Manifest returns the URL to post the manifest to and the manifest JSON. The App is installable by any account, so one App serves every org of a company; it is not listed on the Marketplace.

func RegisterConnectionRoutes

func RegisterConnectionRoutes(api huma.API, syncer *Syncer, store *Store, jobs JobInserter)

RegisterConnectionRoutes wires connections. Any person may read them; only an admin or an owner of a connection's prefix may change one.

func RegisterRoutes

func RegisterRoutes(api huma.API, store *Store, opts RouteOptions)

RegisterRoutes wires the GitHub App setup. Only owners and admins reach it, because the App can write to every repo it is installed on.

func WebhookHandler

func WebhookHandler(store *Store, jobs JobInserter) http.Handler

WebhookHandler receives GitHub's events. A push only brings a sync forward: the sync reads the branch itself, so a forged or replayed event can at most cause a sync that changes nothing.

Types

type APIError

type APIError struct {
	Status int
	Body   string
}

APIError is a GitHub answer other than success or 404.

func (*APIError) Error

func (e *APIError) Error() string

type App

type App struct {
	AppID         int64
	Slug          string
	Name          string
	OwnerLogin    string
	HTMLURL       string
	WebBaseURL    string
	APIBaseURL    string
	ClientID      string
	PrivateKey    []byte
	WebhookSecret []byte
	ClientSecret  []byte
	CreatedBy     string
	CreatedAt     time.Time
}

App is the GitHub App this instance acts as, with its secrets opened.

func (*App) InstallURL

func (a *App) InstallURL() string

InstallURL is where an org owner installs the App.

type Binding

type Binding struct {
	SkillID      string     `json:"skill_id"`
	SkillName    string     `json:"skill_name"`
	ConnectionID string     `json:"connection_id"`
	Path         string     `json:"path"`
	LastCommit   string     `json:"last_commit,omitempty"`
	RemovedAt    *time.Time `json:"removed_from_git_at,omitempty"`
}

Binding is one git-bound skill.

type Change

type Change struct {
	ID           string    `json:"id"`
	ConnectionID string    `json:"connection_id"`
	SkillID      string    `json:"skill_id"`
	SkillName    string    `json:"skill_name"`
	Branch       string    `json:"branch"`
	PRNumber     int       `json:"pr_number"`
	PRURL        string    `json:"pr_url"`
	HeadSHA      string    `json:"head_sha"`
	Digest       string    `json:"digest"`
	RequestedBy  string    `json:"requested_by"`
	State        string    `json:"state"`
	MergeSHA     string    `json:"merge_sha,omitempty"`
	Version      *int      `json:"version,omitempty"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
}

Change is an outbound change: the pull request Skael opened for a publish to a git-bound skill.

type CheckRun

type CheckRun struct {
	Name       string           `json:"name,omitempty"`
	HeadSHA    string           `json:"head_sha,omitempty"`
	Status     string           `json:"status,omitempty"`
	Conclusion string           `json:"conclusion,omitempty"`
	Output     *CheckRunOutput  `json:"output,omitempty"`
	Actions    []CheckRunAction `json:"actions,omitempty"`
}

CheckRun is the part of a check run git sync writes.

type CheckRunAction

type CheckRunAction struct {
	Label       string `json:"label"`
	Description string `json:"description"`
	Identifier  string `json:"identifier"`
}

CheckRunAction is a button on a check run. GitHub sends a requested_action event with its identifier when someone clicks it.

type CheckRunOutput

type CheckRunOutput struct {
	Title   string `json:"title"`
	Summary string `json:"summary"`
}

CheckRunOutput is a check run's title and markdown summary.

type Connection

type Connection struct {
	ID               string     `json:"id"`
	InstallationID   int64      `json:"installation_id"`
	RepoOwner        string     `json:"repo_owner"`
	RepoName         string     `json:"repo_name"`
	Branch           string     `json:"branch"`
	RootPath         string     `json:"root_path"`
	Prefix           string     `json:"prefix"`
	ContestMode      string     `json:"contest_mode"`
	ServiceAccountID string     `json:"service_account_id"`
	CreatedBy        string     `json:"created_by"`
	CreatedAt        time.Time  `json:"created_at"`
	Status           string     `json:"status"`
	LastError        string     `json:"last_error,omitempty"`
	LastSyncedSHA    string     `json:"last_synced_sha,omitempty"`
	LastSyncAt       *time.Time `json:"last_sync_at,omitempty"`
	LastWebhookAt    *time.Time `json:"last_webhook_at,omitempty"`
}

Connection is one repo, branch, root path and name prefix whose skill folders Skael syncs.

func (*Connection) Repo

func (c *Connection) Repo() string

Repo names the connection's repository as owner/name.

type CreateRequest

type CreateRequest struct {
	RepoOwner   string
	RepoName    string
	Branch      string
	RootPath    string
	Prefix      string
	ContestMode string
}

CreateRequest is a connection as a person asks for it.

type Deps

type Deps struct {
	Skills      *skill.Store
	Publisher   *skill.Publisher
	Submissions *submissions.Store
	// Contests and Queue start a contest for a PR head. Nil leaves PR checks
	// at the scan.
	Contests *contest.Store
	Queue    contest.Submitter
	// Suites names the suite a PR contest runs: the skill's latest.
	Suites *evalsuite.Registry
	// Storage holds PR head archives.
	Storage platform.Storage
	// Owners and Users decide whether an outbound change's requester owns the
	// skill, for the PR check.
	Owners skill.OwnerResolver
	Users  *auth.UserStore
	// PublicURL links a check run to Skael's contest page. It is read when
	// the check run is written.
	PublicURL func() string
}

Deps are the registry's parts a sync and a PR check use.

type FolderFile

type FolderFile struct {
	Path       string // relative to the folder
	Content    []byte
	Executable bool
}

FolderFile is one file of a skill folder to commit.

type GitConnectionDetail

type GitConnectionDetail struct {
	Connection
	Bindings []Binding `json:"bindings"`
	Refusals []Refusal `json:"refusals"`
	// Webhooks is true when GitHub reached this instance for the connection.
	// False means changes arrive through the minute-by-minute check only.
	Webhooks bool `json:"webhooks"`
}

GitConnectionDetail is a connection with its skills and refusals. Exported because Huma drops an unexported embedded struct from a response.

type GitHub

type GitHub struct {
	// contains filtered or unexported fields
}

GitHub calls the GitHub API as the App and as its installations.

func NewGitHub

func NewGitHub(app *App, client *http.Client) (*GitHub, error)

NewGitHub builds a client for app.

func (*GitHub) BranchHead

func (g *GitHub) BranchHead(ctx context.Context, installationID int64, owner, repo, branch string) (string, error)

BranchHead returns the commit a branch points at.

func (*GitHub) CommitAuthor

func (g *GitHub) CommitAuthor(ctx context.Context, installationID int64, owner, repo, sha string) (string, error)

CommitAuthor returns the GitHub login of a commit's author, or "" when the commit's email matches no account.

func (*GitHub) CommitFolder

func (g *GitHub) CommitFolder(ctx context.Context, installationID int64, owner, repo, base, branch, dir string,
	files []FolderFile, message string) (string, error)

CommitFolder commits files as the whole content of dir on a new branch cut from base, and returns the new commit. A file under dir that files lacks is deleted, so the folder in git matches the archive exactly.

func (*GitHub) CreateCheckRun

func (g *GitHub) CreateCheckRun(ctx context.Context, installationID int64, owner, repo string, run CheckRun) (int64, error)

CreateCheckRun posts a completed check run and returns its id.

func (*GitHub) DeleteBranch

func (g *GitHub) DeleteBranch(ctx context.Context, installationID int64, owner, repo, branch string) error

DeleteBranch removes a branch Skael created. A branch GitHub already deleted is not an error.

func (*GitHub) GetPullRequest

func (g *GitHub) GetPullRequest(ctx context.Context, installationID int64, owner, repo string, number int) (*PullRequest, error)

GetPullRequest reads one pull request.

func (*GitHub) OpenPullRequest

func (g *GitHub) OpenPullRequest(ctx context.Context, installationID int64, owner, repo, head, base, title, body string) (*PullRequest, error)

OpenPullRequest opens a pull request from head into base.

func (*GitHub) OpenPulls

func (g *GitHub) OpenPulls(ctx context.Context, installationID int64, owner, repo, base string) ([]OpenPull, error)

OpenPulls lists the open pull requests into base.

func (*GitHub) PullFiles

func (g *GitHub) PullFiles(ctx context.Context, installationID int64, owner, repo string, number int) ([]string, error)

PullFiles lists the paths a pull request changes, including the old path of a rename.

func (*GitHub) RepoInstallation

func (g *GitHub) RepoInstallation(ctx context.Context, owner, repo string) (int64, error)

RepoInstallation returns the installation that reaches owner/repo.

func (*GitHub) Repos

func (g *GitHub) Repos(ctx context.Context) ([]Repo, error)

Repos lists every repository the App's installations can reach.

func (*GitHub) Token

func (g *GitHub) Token(ctx context.Context, installationID int64) (string, error)

Token returns an installation token, cached until five minutes before it expires.

func (*GitHub) UpdateCheckRun

func (g *GitHub) UpdateCheckRun(ctx context.Context, installationID int64, owner, repo string, id int64, run CheckRun) error

UpdateCheckRun rewrites a check run.

type GitSkillBinding

type GitSkillBinding struct {
	Bound      bool        `json:"bound"`
	Binding    *Binding    `json:"binding,omitempty"`
	Connection *Connection `json:"connection,omitempty"`
}

GitSkillBinding says where a git-bound skill lives. Bound is false for a native skill.

type JobInserter

type JobInserter interface {
	Insert(ctx context.Context, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
}

JobInserter enqueues a sync.

type ManifestRequest

type ManifestRequest struct {
	Name         string
	Organization string
	WebBaseURL   string
	APIBaseURL   string
	PublicURL    string
}

ManifestRequest is what an admin chooses before GitHub creates the App.

type OpenPull

type OpenPull struct {
	Number  int    `json:"number"`
	HTMLURL string `json:"html_url"`
	Title   string `json:"title"`
	Draft   bool   `json:"draft"`
	Labels  []struct {
		Name string `json:"name"`
	} `json:"labels"`
	Head struct {
		SHA  string `json:"sha"`
		Repo *struct {
			FullName string `json:"full_name"`
		} `json:"repo"`
	} `json:"head"`
	Base struct {
		Repo struct {
			FullName string `json:"full_name"`
		} `json:"repo"`
	} `json:"base"`
}

OpenPull is an open pull request into a connection's branch.

func (*OpenPull) Fork

func (p *OpenPull) Fork() bool

Fork reports whether the pull request comes from another repository.

func (*OpenPull) HasLabel

func (p *OpenPull) HasLabel(label string) bool

HasLabel reports whether the pull request carries label.

type PRHead

type PRHead struct {
	ID        string        `json:"id"`
	SkillName string        `json:"skill_name"`
	Digest    string        `json:"digest"`
	Decision  gate.Decision `json:"decision"`
	ContestID string        `json:"contest_id,omitempty"`
	// contains filtered or unexported fields
}

PRHead is one skill folder at one pull request head.

type Preview

type Preview struct {
	InstallationID int64         `json:"installation_id"`
	HeadSHA        string        `json:"head_sha"`
	Items          []PreviewItem `json:"items"`
}

Preview is what creating a connection would do, at the branch head.

type PreviewItem

type PreviewItem struct {
	Path                string             `json:"path"`
	Name                string             `json:"name"`
	Description         string             `json:"description"`
	Kind                string             `json:"kind"`
	Reason              string             `json:"reason,omitempty"`
	ExistingDescription string             `json:"existing_description,omitempty"`
	ExistingVersion     int                `json:"existing_version,omitempty"`
	Diff                *skill.VersionDiff `json:"diff,omitempty"`
}

PreviewItem is one folder and what creating the connection does with it.

type PullCheck

type PullCheck struct {
	PRNumber         int       `json:"pr_number"`
	PRURL            string    `json:"pr_url"`
	Title            string    `json:"title"`
	HeadSHA          string    `json:"head_sha"`
	Conclusion       string    `json:"conclusion"`
	Fork             bool      `json:"fork"`
	ContestRequested bool      `json:"contest_requested"`
	Heads            []PRHead  `json:"heads"`
	UpdatedAt        time.Time `json:"updated_at"`
	// contains filtered or unexported fields
}

PullCheck is the Skael check on one pull request head.

type PullRequest

type PullRequest struct {
	Number         int    `json:"number"`
	HTMLURL        string `json:"html_url"`
	State          string `json:"state"`
	Merged         bool   `json:"merged"`
	MergeCommitSHA string `json:"merge_commit_sha"`
}

PullRequest is the part of a pull request git sync reads.

type Refusal

type Refusal struct {
	Path      string `json:"path"`
	SkillName string `json:"skill_name"`
	Reason    string `json:"reason"`
}

Refusal is a folder the last sync did not take, and why.

type Repo

type Repo struct {
	InstallationID int64  `json:"installation_id"`
	Owner          string `json:"owner"`
	Name           string `json:"name"`
	DefaultBranch  string `json:"default_branch"`
	Private        bool   `json:"private"`
}

Repo is a repository an installation can reach.

type RouteOptions

type RouteOptions struct {
	// PublicURL is read on each request.
	PublicURL func() string
	// HTTPClient reaches GitHub. Nil means a client with a 30 s timeout.
	HTTPClient *http.Client
}

RouteOptions are the dependencies the routes need beyond the store.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store persists the App and the manifest flows in progress.

func NewStore

func NewStore(pool *pgxpool.Pool, keys *platform.Keyring) *Store

NewStore builds a Store. keys may hold no key; then nothing can be saved.

func (*Store) App

func (s *Store) App(ctx context.Context) (*App, error)

App returns the App with its secrets opened, or (nil, nil) when there is none.

func (*Store) BindingForSkill

func (s *Store) BindingForSkill(ctx context.Context, name string) (*Binding, error)

BindingForSkill returns the binding of a skill name, or (nil, nil) for a native skill.

func (*Store) Bindings

func (s *Store) Bindings(ctx context.Context, connectionID string) ([]Binding, error)

Bindings returns a connection's git-bound skills, by name.

func (*Store) ChangesForSkill

func (s *Store) ChangesForSkill(ctx context.Context, name string) ([]Change, error)

ChangesForSkill returns a skill's outbound changes, newest first.

func (*Store) Complete

func (s *Store) Complete(ctx context.Context, client *http.Client, state, code string) (*App, error)

Complete exchanges the code GitHub returned for the App's credentials and stores them. The state must be one this instance issued in the last hour.

func (*Store) Connection

func (s *Store) Connection(ctx context.Context, id string) (*Connection, error)

Connection returns one connection, or (nil, nil).

func (*Store) ConnectionIDs

func (s *Store) ConnectionIDs(ctx context.Context) ([]string, error)

ConnectionIDs returns every connection id, for the periodic sync.

func (*Store) Connections

func (s *Store) Connections(ctx context.Context) ([]Connection, error)

Connections returns every connection, by repo.

func (*Store) ConnectionsForRepo

func (s *Store) ConnectionsForRepo(ctx context.Context, owner, repo string) ([]Connection, error)

ConnectionsForRepo returns the connections on owner/repo, for a webhook.

func (*Store) Delete

func (s *Store) Delete(ctx context.Context, actor string) (bool, error)

Delete removes the App. GitHub keeps it; its owner deletes it there.

func (*Store) Ignored

func (s *Store) Ignored(ctx context.Context, connectionID string) (map[string]bool, error)

Ignored returns the names a connection never adopts again.

func (*Store) KeysReady

func (s *Store) KeysReady() bool

KeysReady reports whether a master key exists to seal the App's secrets.

func (*Store) PullChecks

func (s *Store) PullChecks(ctx context.Context, connID string) ([]PullCheck, error)

PullChecks returns the newest check of each open pull request on a connection.

func (*Store) Refusals

func (s *Store) Refusals(ctx context.Context, connectionID string) ([]Refusal, error)

Refusals returns what the last sync refused.

func (*Store) RequestContest

func (s *Store) RequestContest(ctx context.Context, connID string, pr int, headSHA string) (bool, error)

RequestContest records a request for a contest on a pull request's newest head. headSHA empty means the newest head Skael checked.

func (*Store) SealedUnreadable added in v0.19.0

func (s *Store) SealedUnreadable(ctx context.Context) (bool, error)

SealedUnreadable reports whether the App exists and its secrets no longer open.

func (*Store) StartManifest

func (s *Store) StartManifest(ctx context.Context, webBase, apiBase, actor string) (string, error)

StartManifest records a manifest flow and returns its state.

func (*Store) TouchWebhook

func (s *Store) TouchWebhook(ctx context.Context, id string) error

TouchWebhook records that GitHub reached this instance for a connection.

type SyncAllArgs

type SyncAllArgs struct{}

SyncAllArgs is the periodic tick that enqueues every connection's sync.

func (SyncAllArgs) Kind

func (SyncAllArgs) Kind() string

type SyncAllWorker

type SyncAllWorker struct {
	river.WorkerDefaults[SyncAllArgs]
	Store *Store
}

SyncAllWorker enqueues a sync for every connection.

func (*SyncAllWorker) Work

Work enqueues through the client running it, so the tick needs no handle of its own.

type SyncArgs

type SyncArgs struct {
	ConnectionID string `json:"connection_id"`
	Force        bool   `json:"force,omitempty"`
}

SyncArgs asks for one connection's sync. Args hold ids only, because River UI shows them to admins.

func (SyncArgs) InsertOpts

func (SyncArgs) InsertOpts() river.InsertOpts

InsertOpts collapses a burst of webhooks and ticks into one sync per connection. River requires the running state in the set, so a push during a running sync waits for the next tick, at most SyncInterval later.

func (SyncArgs) Kind

func (SyncArgs) Kind() string

type SyncWorker

type SyncWorker struct {
	river.WorkerDefaults[SyncArgs]
	Syncer *Syncer
}

SyncWorker runs one connection's sync.

func (*SyncWorker) Timeout

func (w *SyncWorker) Timeout(*river.Job[SyncArgs]) time.Duration

Timeout bounds one sync: a large repo downloads and every changed folder goes through the scan.

func (*SyncWorker) Work

func (w *SyncWorker) Work(ctx context.Context, job *river.Job[SyncArgs]) error

Work syncs. River retries an error; an unreachable repo is not an error but an errored connection.

type Syncer

type Syncer struct {
	// contains filtered or unexported fields
}

Syncer keeps connections in step with their repositories.

func NewSyncer

func NewSyncer(store *Store, client *http.Client) *Syncer

NewSyncer builds a Syncer. Bind must run before any sync.

func (*Syncer) Adopt

func (s *Syncer) Adopt(ctx context.Context, u *auth.User, id, name string) (*Connection, error)

Adopt binds a native skill to a connection after it was refused as taken.

func (*Syncer) Bind

func (s *Syncer) Bind(d Deps)

Bind hands the Syncer the registry's publish path. The River worker is built before the routes build that path, so the two meet here.

func (*Syncer) Bound

func (s *Syncer) Bound(ctx context.Context, name string) (bool, string, error)

Bound reports whether git owns a skill, and names its repo path.

func (*Syncer) Create

func (s *Syncer) Create(ctx context.Context, u *auth.User, req CreateRequest, adopt []string) (*Connection, error)

Create makes the connection, its service account and its ownership, and binds the adopted skills. adopt names the folders to adopt: any from the adopt or match groups of a fresh preview.

func (*Syncer) Delete

func (s *Syncer) Delete(ctx context.Context, u *auth.User, id string) (bool, error)

Delete removes a connection. Its skills become native and keep every version; its service account goes, and with it its ownership membership.

func (*Syncer) Detach

func (s *Syncer) Detach(ctx context.Context, u *auth.User, name string) error

Detach makes a git-bound skill native and keeps the connection from adopting it again.

func (*Syncer) OpenChange

func (s *Syncer) OpenChange(ctx context.Context, name string, archive []byte, note string) (*skill.OutboundChange, error)

OpenChange commits archive to a new branch and opens a pull request for the git-bound skill name, on behalf of the person in ctx. The requester needs no GitHub access: the App authors the commit and the trailer names them.

func (*Syncer) PRHeadArchive

func (s *Syncer) PRHeadArchive(ctx context.Context, id string) ([]byte, error)

PRHeadArchive returns a stored PR head's archive, or nil when there is none.

func (*Syncer) Preview

func (s *Syncer) Preview(ctx context.Context, u *auth.User, req CreateRequest) (*Preview, error)

Preview classifies every skill folder at the branch head.

func (*Syncer) Reconcile

func (s *Syncer) Reconcile(ctx context.Context, id string, force bool) error

Reconcile brings one connection in step with its branch head. A connection that cannot reach its repo is marked errored and no skill changes. force syncs even when the head has not moved, after an adoption.

func (*Syncer) Repos

func (s *Syncer) Repos(ctx context.Context) ([]Repo, error)

Repos lists the repositories the App can reach.

func (*Syncer) SetContestMode

func (s *Syncer) SetContestMode(ctx context.Context, u *auth.User, id, mode string) (*Connection, error)

SetContestMode changes when a connection's PRs get a contest.

func (*Syncer) Store

func (s *Syncer) Store() *Store

Store returns the Syncer's store.

type UserError

type UserError struct {
	// contains filtered or unexported fields
}

UserError is a request the person can correct. Routes answer it with 422.

func (*UserError) Error

func (e *UserError) Error() string

Jump to

Keyboard shortcuts

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