bookkeeper

README

Bookkeeper -- Environment Branches Utility

Placeholder

🟡  Bookkeeper is highly experimental at this time and breaking changes should be anticipated between pre-GA minor releases.

Getting Started

Read more about Bookkeeper in our docs.

This documentation is very new, so please open issues against this repository if you encounter any difficulties with it.

Roadmap

Visit our Roadmap for frequently updated details about what we've accomplished so far and what we're currently working on.

Contributing

The Bookkeeper project accepts contributions via GitHub pull requests.

Visit our Bookkeeper Contributor Guide for more info on how to get started quickly and easily.

Support & Feedback

To report an issue, request a feature, or ask a question, please open an issue here.

Code of Conduct

Participation in the Bookkeeper project is governed by the Contributor Covenant Code of Conduct.

Documentation

Index

• Constants
• type ActionTaken
• type LogLevel
• type RenderRequest
• type RenderResponse
• type RepoCredentials
• type Service
  • func NewService(opts *ServiceOptions) Service
• type ServiceOptions

Constants

const (
	// LogLevelDebug represents DEBUG level logging.
	LogLevelDebug = LogLevel(log.DebugLevel)
	// LogLevelInfo represents INFO level logging. This is the default for the
	// Bookkeeper service when no LogLevel is explicitly specified.
	LogLevelInfo = LogLevel(log.InfoLevel)
	// LogLevelError represents ERROR level logging.
	LogLevelError = LogLevel(log.ErrorLevel)
)

Types

type ActionTaken

type ActionTaken string

ActionTaken indicates what action, if any was taken in response to a RenderRequest.

const (
	// ActionTakenNone represents the case where Bookkeeper responded
	// to a RenderRequest by, effectively, doing nothing. This occurs in cases
	// where the fully rendered manifests that would have been written to the
	// target branch do not differ from what is already present at the head of
	// that branch.
	ActionTakenNone ActionTaken = "NONE"
	// ActionTakenOpenedPR represents the case where Bookkeeper responded to a
	// RenderRequest by opening a new pull request against the target branch.
	ActionTakenOpenedPR ActionTaken = "OPENED_PR"
	// ActionTakenPushedDirectly represents the case where Bookkeeper responded
	// to a RenderRequest by pushing a new commit directly to the target branch.
	ActionTakenPushedDirectly ActionTaken = "PUSHED_DIRECTLY"
	// ActionTakenUpdatedPR represents the case where Bookkeeper responded to a
	// RenderRequest by updating an existing PR.
	ActionTakenUpdatedPR ActionTaken = "UPDATED_PR"
)

type LogLevel

type LogLevel log.Level

LogLevel represents the level of detail logged by the Bookkeeper service's internal logger.

type RenderRequest

type RenderRequest struct {

	// RepoURL is the URL of a remote GitOps repository.
	RepoURL string `json:"repoURL,omitempty"`
	// RepoCreds encapsulates read/write credentials for the remote GitOps
	// repository referenced by the RepoURL field.
	RepoCreds RepoCredentials `json:"repoCreds,omitempty"`
	// Ref specifies either a branch or a precise commit to render manifests from.
	// When this is omitted, the request is assumed to be one to render from the
	// head of the default branch.
	Ref string `json:"ref,omitempty"`
	// TargetBranch is the name of an environment-specific branch in the GitOps
	// repository referenced by the RepoURL field into which plain YAML should be
	// rendered.
	TargetBranch string `json:"targetBranch,omitempty"`
	// Images specifies images to incorporate into environment-specific
	// manifests.
	Images []string `json:"images,omitempty"`
	// CommitMessage offers the opportunity to, optionally, override the first
	// line of the commit message that Bookkeeper would normally generate.
	CommitMessage string `json:"commitMessage,omitempty"`
	// AllowEmpty indicates whether or not Bookkeeper should allow the rendered
	// manifests to be empty. If this is false (the default), Bookkeeper will
	// return an error if the rendered manifests are empty. This is a safeguard
	// against scenarios where a bug of any kind might otherwise cause Bookkeeper
	// to wipe out the contents of the target branch in error.
	AllowEmpty bool `json:"allowEmpty,omitempty"`
	// contains filtered or unexported fields
}

RenderRequest is a request for Bookkeeper to render environment-specific manifests from input in the default branch of the repository specified by RepoURL.

type RenderResponse

type RenderResponse struct {
	ActionTaken ActionTaken `json:"actionTaken,omitempty"`
	// CommitID is the ID (sha) of the commit to the environment-specific branch
	// containing the rendered manifests. This is only set when the OpenPR field
	// of the corresponding RenderRequest was false.
	CommitID string `json:"commitID,omitempty"`
	// PullRequestURL is a URL for a pull request containing the rendered
	// manifests. This is only set when the OpenPR field of the corresponding
	// RenderRequest was true.
	PullRequestURL string `json:"pullRequestURL,omitempty"`
}

RenderResponse encapsulates details of a successful rendering of some environment-specific manifests into an environment-specific branch.

type RepoCredentials

type RepoCredentials struct {
	// SSHPrivateKey is a private key that can be used for both reading from and
	// writing to some remote repository.
	SSHPrivateKey string `json:"sshPrivateKey,omitempty"`
	// Username identifies a principal, which combined with the value of the
	// Password field, can be used for both reading from and writing to some
	// remote repository.
	Username string `json:"username,omitempty"`
	// Password, when combined with the principal identified by the Username
	// field, can be used for both reading from and writing to some remote
	// repository.
	Password string `json:"password,omitempty"`
}

RepoCredentials represents the credentials for connecting to a private git repository.

type Service

type Service interface {
	// RenderManifests handles a bookkeeping request.
	RenderManifests(context.Context, RenderRequest) (RenderResponse, error)
}

Service is an interface for components that can handle bookkeeping requests. Implementations of this interface are transport-agnostic.

func NewService

func NewService(opts *ServiceOptions) Service

NewService returns an implementation of the Service interface for handling bookkeeping requests.

type ServiceOptions

type ServiceOptions struct {
	LogLevel LogLevel
}