Documentation
¶
Overview ¶
Package prmerge is the engine behind `devctl pr merge`: the refusals that come before any wait, the wait of pkg/prwait, the merge, then the wait of pkg/releasewait for the release the merge triggered.
A merge is refused before the first poll for a pull request no wait can turn green (draft, closed, conflicting, behind a strict base; exit 3), for a pull request another human opened (exit 5: bots, GitHub Apps, Giant Swarm's automation accounts and the caller are fine) and in a repository whose team-file entry opts out of agent merges (exit 5, naming the field). Green lands through the merge API as a squash or a rebase with the judged head as the expected head, then the branch goes through the refs API. A base with a merge queue is enqueued instead and the pull request waited for. No protection setting, ruleset or enforce_admins is read to be changed, or written.
The merge is made as the caller: the token is the person's (devctl holds no installation token), so the bypass GitHub honours is the person's: the owning team's or the repository admins', as the alignment engine writes them, never the App's. A merge the review rule declines is exit 3 with GitHub's sentence and the ruleset's bypass actors, so the caller knows whose review or merge it takes.
After the merge the release follows in the same call: the tag auto-release puts on the merge commit, its images and charts resolved to a digest. A merge that no release follows (a repository that does not tag merge commits, commits that warrant no bump) is done at the merge. A release that fails is exit 6 and one not confirmed in time exit 9: both say the merge happened.
Index ¶
Constants ¶
const AgentMergeField = "agentMerge"
AgentMergeField is the team-file entry field that opts a repository out of agent merges.
Variables ¶
This section is empty.
Functions ¶
func IsExecution ¶
IsExecution asserts executionError: GitHub did not do what it accepted to do within the bound (an update-branch that produced no new head).
func IsInvalidConfig ¶
IsInvalidConfig asserts invalidConfigError.
Types ¶
type Config ¶
type Config struct {
// Wait is the wait engine's configuration; its GitHub client, clock,
// progress writer and timeout are the merge's too. Required.
Wait prwait.Config
// Method is squash or rebase; empty is squash.
Method githubclient.MergeMethod
// UpdateBranch: a head behind a strict base is updated from the base
// and the new head waited for, instead of exit 3.
UpdateBranch bool
// Login is the account the token acts as, for the author check; empty
// reads it from GET /user.
Login string
// Policy is the repository's opt-out; nil is [TeamFilePolicy] on the
// GitHub client.
Policy Policy
// Release waits for the release the merge triggered; nil ends the
// command at the merge (--no-release-wait).
Release ReleaseWait
}
Config configures a Merger.
type Merger ¶
type Merger struct {
// contains filtered or unexported fields
}
Merger runs merges.
func (*Merger) Merge ¶
Merge refuses, waits, merges owner/repo#number and waits for the release the merge triggered. The Result is always returned, as far as it was filled; the error is nil on a merge whose release is available or that no release follows, an *agentcli.ExitError with the code of the table otherwise, or a tooling failure.
type Policy ¶
Policy is the repository's say on agent merges: an empty refusal allows the merge, a non-empty one is the sentence exit 5 carries.
func TeamFilePolicy ¶
TeamFilePolicy reads the repository's entry the way pkg/reposetup reads one: the team files of giantswarm/github at main, the entry named after the repository. An entry with `agentMerge: false` refuses; an entry without the field, a repository no team file declares and a repository outside the organisation the team files declare are not opted out. The verdict names the team whose file declares the entry. Team files the token cannot read are an error: the opt-out is not guessed.
type Release ¶ added in v8.91.0
type Release struct {
// Verdict is the release wait's: available, no_release (none follows
// the merge), ci_failed, timeout, not_applicable, usage, auth_required.
Verdict agentcli.Verdict `json:"verdict"`
// Reason is the release wait's reason; empty when available.
Reason string `json:"reason"`
releasewait.Result
}
Release is the release the merge triggered as devctl release wait --pr reports it: its verdict and reason, and its result.
type ReleaseWait ¶ added in v8.91.0
type ReleaseWait func(ctx context.Context, owner, repo string, number int, mergeCommitSHA string, result *releasewait.Result) error
ReleaseWait waits for the release a merge triggered, the wait of devctl release wait --pr given the merge commit, and fills result as far as it got. The error is the release wait's outcome in its own exit-code table.
type Result ¶
type Result struct {
prwait.Result
// MergeCommitSHA is the commit the merge produced; empty when nothing
// merged.
MergeCommitSHA string `json:"mergeCommitSha"`
// Method is squash or rebase.
Method string `json:"method"`
// BranchDeleted: the head branch was deleted after the merge (or was
// gone already). False for a head in a fork, which is left alone.
BranchDeleted bool `json:"branchDeleted"`
// Enqueued: the base has a merge queue and the pull request went
// through it.
Enqueued bool `json:"enqueued"`
// Release is the release the merge triggered; null when no release
// wait ran (--no-release-wait, or nothing merged).
Release *Release `json:"release"`
}
Result is the command's part of the document: the wait's fields and the merge's.
type Verdict ¶ added in v8.85.8
type Verdict struct {
// Refusal is empty when the merge is allowed; otherwise the sentence
// exit 5 carries.
Refusal string
// Team is the slug of the team whose file declares the repository, the
// ruleset's bypass actor for people; empty when no team file does.
Team string
}
Verdict is the repository's say on agent merges.
Source Files