Documentation
¶
Overview ¶
Package gitsync keeps git-bound skills in step with their repositories through one GitHub App per instance.
Index ¶
- Constants
- Variables
- func Manifest(r ManifestRequest, state string) (postURL string, manifest string, err error)
- func RegisterConnectionRoutes(api huma.API, syncer *Syncer, store *Store, jobs JobInserter)
- func RegisterRoutes(api huma.API, store *Store, opts RouteOptions)
- func WebhookHandler(store *Store, jobs JobInserter) http.Handler
- type APIError
- type App
- type Binding
- type Change
- type CheckRun
- type CheckRunAction
- type CheckRunOutput
- type Connection
- type CreateRequest
- type Deps
- type FolderFile
- type GitConnectionDetail
- type GitHub
- func (g *GitHub) BranchHead(ctx context.Context, installationID int64, owner, repo, branch string) (string, error)
- func (g *GitHub) CommitAuthor(ctx context.Context, installationID int64, owner, repo, sha string) (string, error)
- func (g *GitHub) CommitFolder(ctx context.Context, installationID int64, ...) (string, error)
- func (g *GitHub) CreateCheckRun(ctx context.Context, installationID int64, owner, repo string, run CheckRun) (int64, error)
- func (g *GitHub) DeleteBranch(ctx context.Context, installationID int64, owner, repo, branch string) error
- func (g *GitHub) GetPullRequest(ctx context.Context, installationID int64, owner, repo string, number int) (*PullRequest, error)
- func (g *GitHub) OpenPullRequest(ctx context.Context, installationID int64, ...) (*PullRequest, error)
- func (g *GitHub) OpenPulls(ctx context.Context, installationID int64, owner, repo, base string) ([]OpenPull, error)
- func (g *GitHub) PullFiles(ctx context.Context, installationID int64, owner, repo string, number int) ([]string, error)
- func (g *GitHub) RepoInstallation(ctx context.Context, owner, repo string) (int64, error)
- func (g *GitHub) Repos(ctx context.Context) ([]Repo, error)
- func (g *GitHub) Token(ctx context.Context, installationID int64) (string, error)
- func (g *GitHub) UpdateCheckRun(ctx context.Context, installationID int64, owner, repo string, id int64, ...) error
- type GitSkillBinding
- type JobInserter
- type ManifestRequest
- type OpenPull
- type PRHead
- type Preview
- type PreviewItem
- type PullCheck
- type PullRequest
- type Refusal
- type Repo
- type RouteOptions
- type Store
- func (s *Store) App(ctx context.Context) (*App, error)
- func (s *Store) BindingForSkill(ctx context.Context, name string) (*Binding, error)
- func (s *Store) Bindings(ctx context.Context, connectionID string) ([]Binding, error)
- func (s *Store) ChangesForSkill(ctx context.Context, name string) ([]Change, error)
- func (s *Store) Complete(ctx context.Context, client *http.Client, state, code string) (*App, error)
- func (s *Store) Connection(ctx context.Context, id string) (*Connection, error)
- func (s *Store) ConnectionIDs(ctx context.Context) ([]string, error)
- func (s *Store) Connections(ctx context.Context) ([]Connection, error)
- func (s *Store) ConnectionsForRepo(ctx context.Context, owner, repo string) ([]Connection, error)
- func (s *Store) Delete(ctx context.Context, actor string) (bool, error)
- func (s *Store) Ignored(ctx context.Context, connectionID string) (map[string]bool, error)
- func (s *Store) KeysReady() bool
- func (s *Store) PullChecks(ctx context.Context, connID string) ([]PullCheck, error)
- func (s *Store) Refusals(ctx context.Context, connectionID string) ([]Refusal, error)
- func (s *Store) RequestContest(ctx context.Context, connID string, pr int, headSHA string) (bool, error)
- func (s *Store) SealedUnreadable(ctx context.Context) (bool, error)
- func (s *Store) StartManifest(ctx context.Context, webBase, apiBase, actor string) (string, error)
- func (s *Store) TouchWebhook(ctx context.Context, id string) error
- type SyncAllArgs
- type SyncAllWorker
- type SyncArgs
- type SyncWorker
- type Syncer
- func (s *Syncer) Adopt(ctx context.Context, u *auth.User, id, name string) (*Connection, error)
- func (s *Syncer) Bind(d Deps)
- func (s *Syncer) Bound(ctx context.Context, name string) (bool, string, error)
- func (s *Syncer) Create(ctx context.Context, u *auth.User, req CreateRequest, adopt []string) (*Connection, error)
- func (s *Syncer) Delete(ctx context.Context, u *auth.User, id string) (bool, error)
- func (s *Syncer) Detach(ctx context.Context, u *auth.User, name string) error
- func (s *Syncer) OpenChange(ctx context.Context, name string, archive []byte, note string) (*skill.OutboundChange, error)
- func (s *Syncer) PRHeadArchive(ctx context.Context, id string) ([]byte, error)
- func (s *Syncer) Preview(ctx context.Context, u *auth.User, req CreateRequest) (*Preview, error)
- func (s *Syncer) Reconcile(ctx context.Context, id string, force bool) error
- func (s *Syncer) Repos(ctx context.Context) ([]Repo, error)
- func (s *Syncer) SetContestMode(ctx context.Context, u *auth.User, id, mode string) (*Connection, error)
- func (s *Syncer) Store() *Store
- type UserError
Constants ¶
const ( DefaultWebBaseURL = "https://github.com" DefaultAPIBaseURL = "https://api.github.com" )
Public GitHub. An Enterprise Server names its own pair.
const ( ContestOff = "off" ContestOnRequest = "on_request" ContestReady = "ready" )
Contest settings of a connection.
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.
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.
const SyncInterval = time.Minute
SyncInterval is how often every connection is compared with its branch. A webhook only brings that comparison forward.
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 ¶
var ErrAppExists = errors.New("this instance already has a GitHub App; disconnect it first")
ErrAppExists means the instance already has an App.
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.
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.
var ErrNoApp = errors.New("connect GitHub first: this instance has no GitHub App")
ErrNoApp means the instance has no GitHub App yet.
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.
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 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 ¶
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 ¶
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 ¶
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 (*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 ¶
RepoInstallation returns the installation that reaches owner/repo.
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.
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 (*Store) BindingForSkill ¶
BindingForSkill returns the binding of a skill name, or (nil, nil) for a native skill.
func (*Store) ChangesForSkill ¶
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 ¶
Connection returns one connection, or (nil, nil).
func (*Store) ConnectionIDs ¶
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 ¶
ConnectionsForRepo returns the connections on owner/repo, for a webhook.
func (*Store) PullChecks ¶
PullChecks returns the newest check of each open pull request on a connection.
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
SealedUnreadable reports whether the App exists and its secrets no longer open.
func (*Store) StartManifest ¶
StartManifest records a manifest flow and returns its state.
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 ¶
func (w *SyncAllWorker) Work(ctx context.Context, _ *river.Job[SyncAllArgs]) error
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.
type SyncWorker ¶
type SyncWorker struct {
river.WorkerDefaults[SyncArgs]
Syncer *Syncer
}
SyncWorker runs one connection's sync.
type Syncer ¶
type Syncer struct {
// contains filtered or unexported fields
}
Syncer keeps connections in step with their repositories.
func (*Syncer) Bind ¶
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) 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 ¶
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 ¶
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 ¶
PRHeadArchive returns a stored PR head's archive, or nil when there is none.
func (*Syncer) Reconcile ¶
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) 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.