notifiers

README

Notifiers Golang library

This notifiers Go package exposes a lightweight, zero-magic, optional framework for writing new notifiers and extensions.

To write your own notifier using this package, all you need to do is write something that implements the notifiers.Notifier interface and then pass that to notifiers.Main in your Go executable's main method (or wherever). That Main function will set up your notifiers with your config from GCS and your secrets stored on Secret Manager. Feel free to copy the cloudbuild.yaml and Dockerfile in the notifiers that use this package, like http, to build and deploy your own notifier.

In order to filter on specific notifications, you can use the notifiers.EventFilter interface, again, optionally. This library provides two EventFilter implementations:

• notifiers.CELPredicate: This filter uses a compiled-at-startup CEL program string to filter on incoming notifications. It uses a single input variable named build, which is the incoming Build proto from the Pub/Sub notifications. For example, you can write a filter like build.status == Build.Status.SUCCESS || "special" in build.tags to only notify on events that are successful or have the "special" build tag.

Documentation

Index

• Constants
• func AddUTMParams(logURL string, medium UTMMedium) (string, error)
• func FindSecretResourceName(secrets []*Secret, ref string) (string, error)
• func GetEnv(name string) (string, bool)
• func GetSecretRef(config map[string]interface{}, fieldName string) (string, error)
• func Main(notifier Notifier) error
• type BindingResolver
• type CELPredicate
  • func MakeCELPredicate(filter string) (*CELPredicate, error)
  • func (c *CELPredicate) Apply(_ context.Context, build *cbpb.Build) bool
• type Config
• type EventFilter
• type Metadata
• type Notification
• type Notifier
• type Secret
• type SecretConfig
• type SecretGetter
• type Spec
• type UTMMedium

Constants

const (
	// EmailMedium is for Build log URLs that are sent via email.
	EmailMedium UTMMedium = "email"
	// StorageMedium is for Build log URLS that are sent to a storage medium (i.e. BigQuery).
	StorageMedium = "storage"
	// ChatMedium is for Build log URLs that are sent over chat applications.
	ChatMedium = "chat"
	// HTTPMedium is for Build log URLs that are sent over HTTP(S) communication (that does not belong to one of the other mediums).
	HTTPMedium = "http"
	// OtherMedium is for Build log URLs that sent are over a medium that does not correspond to one of the above mediums.
	OtherMedium = "other"
)

Functions

func AddUTMParams

func AddUTMParams(logURL string, medium UTMMedium) (string, error)

AddUTMParams adds UTM campaign tracking parameters to the given Build log URL and returns the new version. The UTM parameters are added to any existing ones, so any existing params will not be ovewritten.

func FindSecretResourceName

func FindSecretResourceName(secrets []*Secret, ref string) (string, error)

FindSecretResourceName is a helper function that returns the Secret's resource name that is associated with the given local reference name.

func GetEnv

func GetEnv(name string) (string, bool)

GetEnv fetches, logs, and returns the given environment variable. The returned boolean is true iff the value is non-empty.

func GetSecretRef

func GetSecretRef(config map[string]interface{}, fieldName string) (string, error)

GetSecretRef is a helper function for getting a Secret's local reference name from the given config.

func Main

func Main(notifier Notifier) error

Main is a function that can be called by `main()` functions in notifier binaries.

Types

type BindingResolver

type BindingResolver interface {
	Resolve(context.Context, SecretGetter, *cbpb.Build) (map[string]string, error)
}

BindingResolver is an object that given a Build and a way to get secrets, returns all bound substitutions from the notifier configuration.

type CELPredicate

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

CELPredicate is an EventFilter that uses a CEL program to determine if notifications should be sent for a given Pub/Sub message.

func MakeCELPredicate

func MakeCELPredicate(filter string) (*CELPredicate, error)

MakeCELPredicate returns a CELPredicate for the given filter string of CEL code.

func (*CELPredicate) Apply

func (c *CELPredicate) Apply(_ context.Context, build *cbpb.Build) bool

Apply returns true iff the underlying CEL program returns true for the given Build.

type Config

type Config struct {
	APIVersion string    `yaml:"apiVersion"`
	Kind       string    `yaml:"kind"`
	Metadata   *Metadata `yaml:"metadata"`
	Spec       *Spec     `yaml:"spec"`
}

Config is the common type for (YAML-based) configuration files for notifications.

type EventFilter

type EventFilter interface {
	// Apply returns true iff the EventFilter is able to execute successfully and matches the given Build.
	Apply(context.Context, *cbpb.Build) bool
}

EventFilter is a type that can be used to filter Builds for notifications.

type Metadata

type Metadata struct {
	Name string `yaml:"name"`
}

Metadata is a KRD-compliant data container used for metadata references.

type Notification

type Notification struct {
	Filter        string                 `yaml:"filter"`
	Delivery      map[string]interface{} `yaml:"delivery"`
	Substitutions map[string]string      `yaml:"substitutions"`
}

Notification is the data container for the fields that are relevant to the configuration of sending the notification.

type Notifier

type Notifier interface {
	SetUp(context.Context, *Config, SecretGetter, BindingResolver) error
	SendNotification(context.Context, *cbpb.Build) error
}

Notifier is the interface type that users should implement for usage in Cloud Build notifiers.

type Secret

type Secret struct {
	LocalName    string `yaml:"name"`
	ResourceName string `yaml:"value"`
}

Secret is a data container matching the local name of a secret to its GCP SecretManager resource name.

type SecretConfig

type SecretConfig struct {
	LocalName string `yaml:"secretRef"`
}

SecretConfig is the data container used in a Spec.Notification config for referencing a secret in the Spec.Secrets list.

type SecretGetter

type SecretGetter interface {
	GetSecret(context.Context, string) (string, error)
}

SecretGetter allows for fetching secrets from some key store.

type Spec

type Spec struct {
	Notification *Notification `yaml:"notification"`
	Secrets      []*Secret     `yaml:"secrets"`
}

Spec is the data container for the fields that are relevant to the functionality of the notifier.

type UTMMedium

type UTMMedium string

UTMMedium is an enum that corresponds to a strict set of values for `utm_medium`.