keeper

README

Tide

Tide is a Prow component for managing a pool of GitHub PRs that match a given set of criteria. It will automatically retest PRs that meet the criteria ("tide comes in") and automatically merge them when they have up-to-date passing test results ("tide goes out").

Open Issues

Documentation

• I JUST WANT MY PR TO MERGE!
• Configuring Tide
• Maintainer's Guide

Features

• Automatically runs batch tests and merges multiple PRs together whenever possible.
• Ensures that PRs are tested against the most recent base branch commit before they are allowed to merge.
• Maintains a GitHub status context that indicates if each PR is in a pool or what requirements are missing.
• Supports blocking merge to individual branches or whole repos using specifically labelled GitHub issues.
• Exposes Prometheus metrics.
• Supports repos that have 'optional' status contexts that shouldn't be required for merge.
• Serves live data about current pools and a history of actions which can be consumed by Deck to populate the Tide dashboard, the PR dashboard, and the Tide history page.
• Scales efficiently so that a single instance with a single bot token can provide merge automation to dozens of orgs and repos with unique merge criteria. Every distinct 'org/repo:branch' combination defines a disjoint merge pool so that merges only affect other PRs in the same branch.
• Provides configurable merge modes ('merge', 'squash', or 'rebase').

History

Tide was created in 2017 by @spxtr to replace Mungegithub's Submit Queue. It was designed to manage a large number of repositories across organizations without using many API rate limit tokens by identifying mergeable PRs with GitHub search queries fulfilled by GitHub's v4 GraphQL API.

Documentation

Overview

Package keeper contains a controller for managing a keeper pool of PRs. The controller will automatically retest PRs in the pool and merge them if they pass tests.

Index

• Constants
• func GetStatusContextLabel() string
• type Action
• type Commit
• type Context
• type Controller
• type DefaultController
  • func NewController(spcSync, spcStatus *scmprovider.Client, fileBrowsers *filebrowser.FileBrowsers, ...) (*DefaultController, error)
  • func (c *DefaultController) GetHistory() *history.History
  • func (c *DefaultController) GetPools() []Pool
  • func (c *DefaultController) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (c *DefaultController) Shutdown()
  • func (c *DefaultController) Sync() error
• type GraphQLAuthor
• type GraphQLBaseRef
• type PRNode
• type Pool
• type PullRequest
• type Repository
• type SCMUser

Constants

const (

	// StatusContextLabelEnvVar is the environment variable we look to for the overriding status context label.
	StatusContextLabelEnvVar = "LIGHTHOUSE_KEEPER_STATUS_CONTEXT_LABEL"
)

Functions

func GetStatusContextLabel

func GetStatusContextLabel() string

GetStatusContextLabel gets the label used for the keeper status context, defaulting to "keeper" if the env var above isn't set.

Types

type Action

type Action string

Action represents what actions the controller can take. It will take exactly one action each sync.

const (
	Wait         Action = "WAIT"
	Trigger      Action = "TRIGGER"
	TriggerBatch Action = "TRIGGER_BATCH"
	Merge        Action = "MERGE"
	MergeBatch   Action = "MERGE_BATCH"
	PoolBlocked  Action = "BLOCKED"
)

Constants for various actions the controller might take

type Commit

type Commit struct {
	Status struct {
		Contexts []Context
	}
	OID githubql.String `graphql:"oid"`
}

Commit holds graphql data about commits and which contexts they have

type Context

type Context struct {
	Context     githubql.String
	Description githubql.String
	State       githubql.StatusState
}

Context holds graphql response data for github contexts.

type Controller

type Controller interface {
	Sync() error
	Shutdown()
	GetPools() []Pool
	ServeHTTP(w http.ResponseWriter, r *http.Request)
	GetHistory() *history.History
}

Controller the interface for all keeper controllers whether regular or the GitHub App flavour which has to handle tokens differently

type DefaultController

type DefaultController struct {
	History *history.History
	// contains filtered or unexported fields
}

DefaultController knows how to sync PRs and PJs.

func NewController

func NewController(spcSync, spcStatus *scmprovider.Client, fileBrowsers *filebrowser.FileBrowsers, launcherClient launcher, tektonClient tektonclient.Interface, lighthouseClient clientset.Interface, ns string, cfg config.Getter, gc git.Client, maxRecordsPerPool int, historyURI, statusURI string, logger *logrus.Entry) (*DefaultController, error)

NewController makes a DefaultController out of the given clients.

func (*DefaultController) GetHistory

func (c *DefaultController) GetHistory() *history.History

GetHistory returns the history

func (*DefaultController) GetPools

func (c *DefaultController) GetPools() []Pool

GetPools returns the pool status

func (*DefaultController) ServeHTTP

func (c *DefaultController) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*DefaultController) Shutdown

func (c *DefaultController) Shutdown()

Shutdown signals the statusController to stop working and waits for it to finish its last update loop before terminating. DefaultController.Sync() should not be used after this function is called.

func (*DefaultController) Sync

func (c *DefaultController) Sync() error

Sync runs one sync iteration.

type GraphQLAuthor

type GraphQLAuthor struct {
	Login githubql.String
}

GraphQLAuthor represents the author in the GitHub GraphQL layout

type GraphQLBaseRef

type GraphQLBaseRef struct {
	Name   githubql.String
	Prefix githubql.String
}

GraphQLBaseRef represents the author in the GitHub GraphQL layout

type PRNode

type PRNode struct {
	PullRequest PullRequest `graphql:"... on PullRequest"`
}

PRNode a node containing a PR

type Pool

type Pool struct {
	Org    string
	Repo   string
	Branch string

	// PRs with passing tests, pending tests, and missing or failed tests.
	// Note that these results are rolled up. If all tests for a PR are passing
	// except for one pending, it will be in PendingPRs.
	SuccessPRs []PullRequest
	PendingPRs []PullRequest
	MissingPRs []PullRequest

	// Empty if there is no pending batch.
	BatchPending []PullRequest

	// Which action did we last take, and to what target(s), if any.
	Action   Action
	Target   []PullRequest
	Blockers []blockers.Blocker
	Error    string
}

Pool represents information about a keeper pool. There is one for every org/repo/branch combination that has PRs in the pool.

type PullRequest

type PullRequest struct {
	Number      githubql.Int
	Author      GraphQLAuthor
	BaseRef     GraphQLBaseRef
	HeadRefName githubql.String `graphql:"headRefName"`
	HeadRefOID  githubql.String `graphql:"headRefOid"`
	BaseRefOID  githubql.String
	Mergeable   githubql.MergeableState
	Repository  Repository
	Commits     struct {
		Nodes []struct {
			Commit Commit
		}
	} `graphql:"commits(last: 4)"`
	Labels struct {
		Nodes []struct {
			Name githubql.String
		}
	} `graphql:"labels(first: 100)"`
	Milestone *struct {
		Title githubql.String
	}
	Body      githubql.String
	Title     githubql.String
	UpdatedAt githubql.DateTime
}

PullRequest holds graphql data about a PR, including its commits and their contexts.

type Repository

type Repository struct {
	Name          githubql.String
	NameWithOwner githubql.String
	URL           githubql.String
	Owner         SCMUser
}

Repository holds graphql/query data about repositories

type SCMUser

type SCMUser struct {
	Login githubql.String
}

SCMUser holds the username